@powerlines/engine 0.45.3 → 0.46.1

package/dist/api.mjs

@@ -1,5 +1,5 @@
-import { a as mergeConfigs, i as callHook, s as writeMetaFile, t as PowerlinesExecutionContext } from "./execution-context-Bkxp1fML.mjs";
-import { a as isIncludeMatchFound, i as getTsconfigFilePath, r as getParsedTypeScriptConfig } from "./tsconfig-CI6bla4E.mjs";
+import { a as mergeConfigs, i as callHook, s as writeMetaFile, t as PowerlinesExecutionContext } from "./execution-context-CgDuoi8o.mjs";
+import { a as isIncludeMatchFound, i as getTsconfigFilePath, r as getParsedTypeScriptConfig } from "./tsconfig-MeFEs21S.mjs";
 import { n as createProgram } from "./ts-morph-D0CaA37w.mjs";
 import { toArray } from "@stryke/convert/to-array";
 import { resolvePackage } from "@stryke/fs/resolve";
@@ -15,7 +15,6 @@ import { replaceExtension, replacePath } from "@stryke/path/replace";
 import chalk from "chalk";
 import defu from "defu";
 import { joinPaths } from "@stryke/path/join-paths";
-import { titleCase } from "@stryke/string-format/title-case";
 import { getTypescriptFileHeader } from "@powerlines/core/lib/utilities/file-header";
 import { format, formatFolder } from "@powerlines/core/lib/utilities/format";
 import { formatLogMessage } from "@storm-software/config-tools/logger/console";
@@ -29,6 +28,7 @@ import { getUnique } from "@stryke/helpers/get-unique";
 import { omit } from "@stryke/helpers/omit";
 import { findFileName, findFilePath, relativePath } from "@stryke/path/file-path-fns";
 import { isParentPath } from "@stryke/path/is-parent-path";
+import { titleCase } from "@stryke/string-format/title-case";
 import { isError } from "@stryke/type-checks/is-error";
 import { isFunction } from "@stryke/type-checks/is-function";
 import { isNumber } from "@stryke/type-checks/is-number";
@@ -358,11 +358,11 @@ async function installDependencies(context) {
 //#endregion
 //#region src/_internal/helpers/resolve-tsconfig.ts
 function getTsconfigDtsPath(context) {
-	return joinPaths(relativePath(joinPaths(context.options.cwd, context.options.root), findFilePath(context.typesPath)), findFileName(context.typesPath));
+	return joinPaths(relativePath(joinPaths(context.config.cwd, context.config.root), findFilePath(context.typesPath)), findFileName(context.typesPath));
 }
 async function resolveTsconfigChanges(context) {
-	const tsconfig = getParsedTypeScriptConfig(context.options.cwd, context.options.root, context.config.tsconfig, context.config.tsconfigRaw);
-	const tsconfigJson = await readJsonFile(getTsconfigFilePath(context.options.cwd, context.options.root, context.config.tsconfig));
+	const tsconfig = getParsedTypeScriptConfig(context.config.cwd, context.config.root, context.config.tsconfig, context.config.tsconfigRaw);
+	const tsconfigJson = await readJsonFile(getTsconfigFilePath(context.config.cwd, context.config.root, context.config.tsconfig));
 	tsconfigJson.compilerOptions ??= {};
 	if (context.config.output.dts !== false) {
 		const dtsRelativePath = getTsconfigDtsPath(context);
@@ -452,249 +452,15 @@ var PowerlinesExecution = class PowerlinesExecution {
 	* The Powerlines context
 	*/
 	#context;
-	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.copy) {
-			context.debug("Copying project's files from build output directory.");
-			const destinationPath = isParentPath(appendPath(context.config.output.path, context.config.cwd), appendPath(context.config.root, context.config.cwd)) ? joinPaths(context.config.output.copy.path, relativePath(appendPath(context.config.root, context.config.cwd), appendPath(context.config.output.path, context.config.cwd))) : joinPaths(context.config.output.copy.path, "dist");
-			const sourcePath = context.config.output.path;
-			if (existsSync(sourcePath) && sourcePath !== destinationPath) {
-				context.debug(`Copying files from project's build output directory (${context.config.output.path}) to the project's copy/publish directory (${destinationPath}).`);
-				await copyFiles(sourcePath, destinationPath);
-			} else context.warn(`The source path for the copy operation ${!existsSync(sourcePath) ? "does not exist" : "is the same as the destination path"}. Source: ${sourcePath}, Destination: ${destinationPath}. Skipping copying of build output files.`);
-			if (context.config.output.copy.assets && Array.isArray(context.config.output.copy.assets)) await Promise.all(context.config.output.copy.assets.map(async (asset) => {
-				context.trace(`Copying asset(s): ${chalk.redBright(context.config.cwd === asset.input ? asset.glob : appendPath(asset.glob, replacePath(asset.input, context.config.cwd)))} -> ${chalk.greenBright(appendPath(asset.glob, replacePath(asset.output, context.config.cwd)))} ${Array.isArray(asset.ignore) && asset.ignore.length > 0 ? ` (ignoring: ${asset.ignore.map((i) => chalk.yellowBright(i)).join(", ")})` : ""}`);
-				await context.fs.copy(asset, asset.output);
-			}));
-		} else context.debug("No copy configuration found for the project output. Skipping the copying of build output files.");
-		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));
-		}));
-	}
-	/**
-	* 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 (isDuplicate(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.config.cwd, this.context.config.root] });
-		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.root });
-			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\`.`);
-			}
-		}
-	}
-	/**
-	* Generate the Powerlines TypeScript declaration file
-	*
-	* @remarks
-	* This method will generate the TypeScript declaration file for the Powerlines project, including any types provided by plugins.
-	*
-	* @param context - The environment context to use for generating the TypeScript declaration file
-	* @returns A promise that resolves when the TypeScript declaration file has been generated
-	*/
-	async #types(context) {
-		context.debug(`Preparing the TypeScript definitions for the Powerlines project.`);
-		if (context.fs.existsSync(context.typesPath)) await context.fs.remove(context.typesPath);
-		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 { code, directives } = await emitBuiltinTypes(context, (await context.getBuiltins()).reduce((ret, builtin) => {
-			const formatted = replacePath(builtin.path, context.config.cwd);
-			if (!ret.includes(formatted)) ret.push(formatted);
-			return ret;
-		}, []));
-		context.debug(`Generating TypeScript declaration file ${context.typesPath}.`);
-		const merge = async (currentResult, previousResult) => {
-			if (!isSetString(currentResult) && !isSetObject(currentResult) && !isSetString(previousResult) && !isSetObject(previousResult)) return {
-				code,
-				directives
-			};
-			const previous = (await format(context, context.typesPath, isSetString(previousResult) ? previousResult : isSetObject(previousResult) ? previousResult.code : "")).trim().replace(code, "").trim();
-			const current = (await format(context, context.typesPath, isSetString(currentResult) ? currentResult : isSetObject(currentResult) ? currentResult.code : "")).trim().replace(previous, "").trim().replace(code, "").trim();
-			return {
-				directives: [...isSetObject(currentResult) && currentResult.directives ? currentResult.directives : [], ...isSetObject(previousResult) && previousResult.directives ? previousResult.directives : []],
-				code: await format(context, context.typesPath, `${!previous.includes(getTypescriptFileHeader(context)) && !current.includes(getTypescriptFileHeader(context)) ? `${code}\n` : ""}${previous}\n${current}`.trim())
-			};
-		};
-		const asNextParam = (previousResult) => isObject(previousResult) ? previousResult.code : previousResult;
-		let result = await this.callHook("types", {
-			environment: context,
-			sequential: true,
-			order: "pre",
-			result: "merge",
-			merge,
-			asNextParam
-		}, code);
-		if (result) {
-			if (isSetObject(result)) {
-				code = result.code;
-				if (Array.isArray(result.directives) && result.directives.length > 0) directives = getUnique([...directives, ...result.directives]).filter(Boolean);
-			} else if (isSetString(result)) code = result;
-		}
-		result = await this.callHook("types", {
-			environment: context,
-			sequential: true,
-			order: "normal",
-			result: "merge",
-			merge,
-			asNextParam
-		}, code);
-		if (result) {
-			if (isSetObject(result)) {
-				code = result.code;
-				if (Array.isArray(result.directives) && result.directives.length > 0) directives = getUnique([...directives, ...result.directives]).filter(Boolean);
-			} else if (isSetString(result)) code = result;
-		}
-		result = await this.callHook("types", {
-			environment: context,
-			sequential: true,
-			order: "post",
-			result: "merge",
-			merge,
-			asNextParam
-		}, code);
-		if (result) {
-			if (isSetObject(result)) {
-				code = result.code;
-				if (Array.isArray(result.directives) && result.directives.length > 0) directives = getUnique([...directives, ...result.directives]).filter(Boolean);
-			} else if (isSetString(result)) code = result;
-		}
-		if (isSetString(code?.trim()) || directives.length > 0) await context.fs.write(context.typesPath, `${directives.length > 0 ? `${directives.map((directive) => `/// <reference types="${directive}" />`).join("\n")}
-
-` : ""}${getTypescriptFileHeader(context, {
-			directive: null,
-			prettierIgnore: false
-		})}
-
-${formatTypes(code)}
-`);
-	}
 	/**
 	* Initialize a Powerlines API instance
 	*
 	* @param options - The options to initialize the API with
 	* @returns A new instance of the Powerlines API
 	*/
-	static async init(options, initialConfig) {
-		const api = new PowerlinesExecution(await PowerlinesExecutionContext.init(options, initialConfig ?? {}));
-		api.#context.config.initialConfig = initialConfig ?? {};
-		await api.setup();
+	static async from(options, initialConfig) {
+		const api = new PowerlinesExecution(await PowerlinesExecutionContext.fromInitialConfig(options, initialConfig ?? {}));
+		await api.init();
 		return api;
 	}
 	/**
@@ -704,37 +470,6 @@ ${formatTypes(code)}
 		return this.#context;
 	}
 	/**
-	* Initialize the execution API with the provided configuration options
-	*/
-	async setup() {
-		await this.#context.setup();
-		this.#context.$$internal = {
-			api: this,
-			addPlugin: this.addPlugin.bind(this)
-		};
-		const timer = this.#context.timer("Initialization");
-		for (const plugin of this.#context.config.plugins.flatMap((p) => toArray(p)) ?? []) await this.addPlugin(plugin);
-		if (this.#context.plugins.length === 0) this.#context.warn({
-			meta: { category: "plugins" },
-			message: "No Powerlines plugins were specified in the options. Please ensure this is correct, as it is generally not recommended."
-		});
-		else this.#context.info({
-			meta: { category: "plugins" },
-			message: `Loaded ${this.#context.plugins.length} ${titleCase(this.#context.config.framework)} plugin${this.#context.plugins.length > 1 ? "s" : ""}: \n${this.#context.plugins.map((plugin, index) => ` ${index + 1}. ${colorText(plugin.name)}`).join("\n")}`
-		});
-		const pluginConfig = await this.callHook("config", {
-			environment: await this.#context.getEnvironment(),
-			sequential: true,
-			result: "merge",
-			merge: mergeConfigs
-		});
-		if (pluginConfig) {
-			this.#context.config.pluginConfig = pluginConfig;
-			await this.#context.setup();
-		}
-		timer();
-	}
-	/**
 	* Generate the Powerlines typescript declaration file
 	*
 	* @remarks
@@ -745,9 +480,8 @@ ${formatTypes(code)}
 	async types(inlineConfig = { command: "types" }) {
 		this.context.debug(" Aggregating configuration options for the Powerlines project");
 		inlineConfig.command ??= "types";
-		this.context.config.inlineConfig = inlineConfig;
-		await this.setup();
-		await this.#executeEnvironments(async (context) => {
+		await this.context.setInlineConfig(inlineConfig);
+		await this.executeEnvironments(async (context) => {
 			context.debug(`Initializing the processing options for the Powerlines project.`);
 			await this.callHook("configResolved", {
 				environment: context,
@@ -779,7 +513,7 @@ ${formatTypes(code)}
 				context.info(`Running \`prepare\` command as the meta checksum has changed since the last run.`);
 				await this.prepare(defu({ output: { types: false } }, inlineConfig));
 			}
-			await this.#types(context);
+			await this.handleTypes(context);
 			this.context.debug("Formatting files generated during the types step.");
 			await format(context, context.typesPath, await context.fs.read(context.typesPath) ?? "");
 			await writeMetaFile(context);
@@ -796,9 +530,8 @@ ${formatTypes(code)}
 	*/
 	async prepare(inlineConfig = { command: "prepare" }) {
 		inlineConfig.command ??= "prepare";
-		this.context.config.inlineConfig = inlineConfig;
-		await this.setup();
-		await this.#executeEnvironments(async (context) => {
+		await this.context.setInlineConfig(inlineConfig);
+		await this.executeEnvironments(async (context) => {
 			context.debug(`Initializing the processing options for the Powerlines project.`);
 			await this.callHook("configResolved", {
 				environment: context,
@@ -848,7 +581,7 @@ ${formatTypes(code)}
 				environment: context,
 				order: "post"
 			});
-			if (context.config.output.types !== false) await this.#types(context);
+			if (context.config.output.types !== false) await this.handleTypes(context);
 			this.context.debug("Formatting files generated during the prepare step.");
 			await Promise.all([formatFolder(context, context.builtinsPath), formatFolder(context, context.entryPath)]);
 			await writeMetaFile(context);
@@ -867,7 +600,7 @@ ${formatTypes(code)}
 	async new(inlineConfig) {
 		inlineConfig.command ??= "new";
 		await this.prepare(inlineConfig);
-		await this.#executeEnvironments(async (context) => {
+		await this.executeEnvironments(async (context) => {
 			context.debug("Initializing the processing options for the Powerlines project.");
 			await this.callHook("new", {
 				environment: context,
@@ -916,7 +649,7 @@ ${formatTypes(code)}
 	async clean(inlineConfig = { command: "clean" }) {
 		inlineConfig.command ??= "clean";
 		await this.prepare(inlineConfig);
-		await this.#executeEnvironments(async (context) => {
+		await this.executeEnvironments(async (context) => {
 			context.debug("Cleaning the project's dist and artifacts directories.");
 			await context.fs.remove(joinPaths(context.config.cwd, context.config.output.path));
 			await context.fs.remove(joinPaths(context.config.cwd, context.config.root, context.config.output.artifactsPath));
@@ -935,7 +668,7 @@ ${formatTypes(code)}
 	async lint(inlineConfig = { command: "lint" }) {
 		inlineConfig.command ??= "lint";
 		await this.prepare(inlineConfig);
-		await this.#executeEnvironments(async (context) => {
+		await this.executeEnvironments(async (context) => {
 			await this.callHook("lint", {
 				environment: context,
 				sequential: false
@@ -951,7 +684,7 @@ ${formatTypes(code)}
 	async test(inlineConfig = { command: "test" }) {
 		inlineConfig.command ??= "test";
 		await this.prepare(inlineConfig);
-		await this.#executeEnvironments(async (context) => {
+		await this.executeEnvironments(async (context) => {
 			await this.callHook("test", {
 				environment: context,
 				sequential: false
@@ -969,17 +702,15 @@ ${formatTypes(code)}
 	*/
 	async build(inlineConfig = { command: "build" }) {
 		inlineConfig.command ??= "build";
+		await this.context.setInlineConfig(inlineConfig);
 		await this.context.generateChecksum();
 		if (this.context.meta.checksum !== this.context.persistedMeta?.checksum || this.context.config.skipCache) {
 			this.context.info(!this.context.persistedMeta?.checksum ? "No previous build cache found. Preparing the project for the initial build." : this.context.meta.checksum !== this.context.persistedMeta.checksum ? "The project has been modified since the last time `prepare` was ran. Re-preparing the project." : "The project is configured to skip cache. Re-preparing the project.");
 			await this.prepare(inlineConfig);
-		} else {
-			this.context.config.inlineConfig = inlineConfig;
-			await this.context.setup();
 		}
-		if (this.context.config.singleBuild) await this.#handleBuild(await this.#context.toEnvironment());
-		else await this.#executeEnvironments(async (context) => {
-			await this.#handleBuild(context);
+		if (this.context.config.singleBuild) await this.handleBuild(await this.#context.toEnvironment());
+		else await this.executeEnvironments(async (context) => {
+			await this.handleBuild(context);
 		});
 	}
 	/**
@@ -990,8 +721,9 @@ ${formatTypes(code)}
 	*/
 	async docs(inlineConfig = { command: "docs" }) {
 		inlineConfig.command ??= "docs";
+		await this.context.setInlineConfig(inlineConfig);
 		await this.prepare(inlineConfig);
-		await this.#executeEnvironments(async (context) => {
+		await this.executeEnvironments(async (context) => {
 			context.debug("Writing documentation for the Powerlines project artifacts.");
 			await this.callHook("docs", { environment: context });
 		});
@@ -1006,8 +738,9 @@ ${formatTypes(code)}
 	*/
 	async deploy(inlineConfig = { command: "deploy" }) {
 		inlineConfig.command ??= "deploy";
+		await this.context.setInlineConfig(inlineConfig);
 		await this.prepare(inlineConfig);
-		await this.#executeEnvironments(async (context) => {
+		await this.executeEnvironments(async (context) => {
 			await this.callHook("deploy", { environment: context });
 		});
 	}
@@ -1020,7 +753,7 @@ ${formatTypes(code)}
 	* @returns A promise that resolves when the finalization process has completed
 	*/
 	async finalize() {
-		await this.#executeEnvironments(async (context) => {
+		await this.executeEnvironments(async (context) => {
 			await this.callHook("finalize", { environment: context });
 			await context.fs.dispose();
 			if (existsSync(context.cachePath) && !(await listFiles(joinPaths(context.cachePath, "**/*")))?.length) await removeDirectory(context.cachePath);
@@ -1052,13 +785,40 @@ ${formatTypes(code)}
 		this.#context = context;
 	}
 	/**
+	* Initialize the execution API with the provided configuration options
+	*/
+	async init() {
+		this.#context.$$internal = {
+			api: this,
+			addPlugin: this.addPlugin.bind(this)
+		};
+		const timer = this.#context.timer("Initialization");
+		for (const plugin of this.#context.config.plugins.flatMap((p) => toArray(p)) ?? []) await this.addPlugin(plugin);
+		if (this.#context.plugins.length === 0) this.#context.warn({
+			meta: { category: "plugins" },
+			message: "No Powerlines plugins were specified in the options. Please ensure this is correct, as it is generally not recommended."
+		});
+		else this.#context.info({
+			meta: { category: "plugins" },
+			message: `Loaded ${this.#context.plugins.length} ${titleCase(this.#context.config.framework)} plugin${this.#context.plugins.length > 1 ? "s" : ""}: \n${this.#context.plugins.map((plugin, index) => ` ${index + 1}. ${colorText(plugin.name)}`).join("\n")}`
+		});
+		const pluginConfig = await this.callHook("config", {
+			environment: await this.#context.getEnvironment(),
+			sequential: true,
+			result: "merge",
+			merge: mergeConfigs
+		});
+		if (pluginConfig) await this.context.setPluginConfig(pluginConfig);
+		timer();
+	}
+	/**
 	* 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);
+			const result = await this.initPlugin(config);
 			if (!result) return;
 			for (const plugin of result) {
 				this.context.debug({
@@ -1069,6 +829,239 @@ ${formatTypes(code)}
 			}
 		}
 	}
+	/**
+	* 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.createEnvironment(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));
+		}));
+	}
+	/**
+	* 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 (isDuplicate(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.config.cwd, this.context.config.root] });
+		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.root });
+			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\`.`);
+			}
+		}
+	}
+	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.copy) {
+			context.debug("Copying project's files from build output directory.");
+			const destinationPath = isParentPath(appendPath(context.config.output.path, context.config.cwd), appendPath(context.config.root, context.config.cwd)) ? joinPaths(context.config.output.copy.path, relativePath(appendPath(context.config.root, context.config.cwd), appendPath(context.config.output.path, context.config.cwd))) : joinPaths(context.config.output.copy.path, "dist");
+			const sourcePath = context.config.output.path;
+			if (existsSync(sourcePath) && sourcePath !== destinationPath) {
+				context.debug(`Copying files from project's build output directory (${context.config.output.path}) to the project's copy/publish directory (${destinationPath}).`);
+				await copyFiles(sourcePath, destinationPath);
+			} else context.warn(`The source path for the copy operation ${!existsSync(sourcePath) ? "does not exist" : "is the same as the destination path"}. Source: ${sourcePath}, Destination: ${destinationPath}. Skipping copying of build output files.`);
+			if (context.config.output.copy.assets && Array.isArray(context.config.output.copy.assets)) await Promise.all(context.config.output.copy.assets.map(async (asset) => {
+				context.trace(`Copying asset(s): ${chalk.redBright(context.config.cwd === asset.input ? asset.glob : appendPath(asset.glob, replacePath(asset.input, context.config.cwd)))} -> ${chalk.greenBright(appendPath(asset.glob, replacePath(asset.output, context.config.cwd)))} ${Array.isArray(asset.ignore) && asset.ignore.length > 0 ? ` (ignoring: ${asset.ignore.map((i) => chalk.yellowBright(i)).join(", ")})` : ""}`);
+				await context.fs.copy(asset, asset.output);
+			}));
+		} else context.debug("No copy configuration found for the project output. Skipping the copying of build output files.");
+		await this.callHook("build", {
+			environment: context,
+			order: "post"
+		});
+	}
+	/**
+	* Generate the Powerlines TypeScript declaration file
+	*
+	* @remarks
+	* This method will generate the TypeScript declaration file for the Powerlines project, including any types provided by plugins.
+	*
+	* @param context - The environment context to use for generating the TypeScript declaration file
+	* @returns A promise that resolves when the TypeScript declaration file has been generated
+	*/
+	async handleTypes(context) {
+		context.debug(`Preparing the TypeScript definitions for the Powerlines project.`);
+		if (context.fs.existsSync(context.typesPath)) await context.fs.remove(context.typesPath);
+		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 { code, directives } = await emitBuiltinTypes(context, (await context.getBuiltins()).reduce((ret, builtin) => {
+			const formatted = replacePath(builtin.path, context.config.cwd);
+			if (!ret.includes(formatted)) ret.push(formatted);
+			return ret;
+		}, []));
+		context.debug(`Generating TypeScript declaration file ${context.typesPath}.`);
+		const merge = async (currentResult, previousResult) => {
+			if (!isSetString(currentResult) && !isSetObject(currentResult) && !isSetString(previousResult) && !isSetObject(previousResult)) return {
+				code,
+				directives
+			};
+			const previous = (await format(context, context.typesPath, isSetString(previousResult) ? previousResult : isSetObject(previousResult) ? previousResult.code : "")).trim().replace(code, "").trim();
+			const current = (await format(context, context.typesPath, isSetString(currentResult) ? currentResult : isSetObject(currentResult) ? currentResult.code : "")).trim().replace(previous, "").trim().replace(code, "").trim();
+			return {
+				directives: [...isSetObject(currentResult) && currentResult.directives ? currentResult.directives : [], ...isSetObject(previousResult) && previousResult.directives ? previousResult.directives : []],
+				code: await format(context, context.typesPath, `${!previous.includes(getTypescriptFileHeader(context)) && !current.includes(getTypescriptFileHeader(context)) ? `${code}\n` : ""}${previous}\n${current}`.trim())
+			};
+		};
+		const asNextParam = (previousResult) => isObject(previousResult) ? previousResult.code : previousResult;
+		let result = await this.callHook("types", {
+			environment: context,
+			sequential: true,
+			order: "pre",
+			result: "merge",
+			merge,
+			asNextParam
+		}, code);
+		if (result) {
+			if (isSetObject(result)) {
+				code = result.code;
+				if (Array.isArray(result.directives) && result.directives.length > 0) directives = getUnique([...directives, ...result.directives]).filter(Boolean);
+			} else if (isSetString(result)) code = result;
+		}
+		result = await this.callHook("types", {
+			environment: context,
+			sequential: true,
+			order: "normal",
+			result: "merge",
+			merge,
+			asNextParam
+		}, code);
+		if (result) {
+			if (isSetObject(result)) {
+				code = result.code;
+				if (Array.isArray(result.directives) && result.directives.length > 0) directives = getUnique([...directives, ...result.directives]).filter(Boolean);
+			} else if (isSetString(result)) code = result;
+		}
+		result = await this.callHook("types", {
+			environment: context,
+			sequential: true,
+			order: "post",
+			result: "merge",
+			merge,
+			asNextParam
+		}, code);
+		if (result) {
+			if (isSetObject(result)) {
+				code = result.code;
+				if (Array.isArray(result.directives) && result.directives.length > 0) directives = getUnique([...directives, ...result.directives]).filter(Boolean);
+			} else if (isSetString(result)) code = result;
+		}
+		if (isSetString(code?.trim()) || directives.length > 0) await context.fs.write(context.typesPath, `${directives.length > 0 ? `${directives.map((directive) => `/// <reference types="${directive}" />`).join("\n")}
+
+` : ""}${getTypescriptFileHeader(context, {
+			directive: null,
+			prettierIgnore: false
+		})}
+
+${formatTypes(code)}
+`);
+	}
 };
 
 //#endregion
@@ -1089,37 +1082,13 @@ var PowerlinesAPI = class PowerlinesAPI extends PowerlinesExecution {
 	* @param initialConfig - The initial configuration for the API, which can be used to provide additional context or override certain configuration values during initialization. This is particularly useful when initializing the API from a CLI command, where the CLI flags can be passed as part of the initial configuration to ensure they are properly merged with the configuration file and made available to plugins during their setup and execution.
 	* @returns A new instance of the Powerlines API
 	*/
-	static async init(options, initialConfig) {
-		const api = new PowerlinesAPI(await PowerlinesExecutionContext.init({
+	static async from(options, initialConfig) {
+		const api = new PowerlinesAPI(await PowerlinesExecutionContext.fromInitialConfig({
 			executionId: uuid(),
 			executionIndex: 0,
 			...options
 		}, initialConfig ?? {}));
-		api.context.$$internal = {
-			api,
-			addPlugin: api.addPlugin.bind(api)
-		};
-		const timer = api.context.timer("Initialization");
-		for (const plugin of api.context.config.plugins.flatMap((p) => toArray(p)) ?? []) await api.addPlugin(plugin);
-		if (api.context.plugins.length === 0) api.context.warn({
-			meta: { category: "plugins" },
-			message: "No Powerlines plugins were specified in the options. Please ensure this is correct, as it is generally not recommended."
-		});
-		else api.context.info({
-			meta: { category: "plugins" },
-			message: `Loaded ${api.context.plugins.length} ${titleCase(api.context.config.framework)} plugin${api.context.plugins.length > 1 ? "s" : ""}: \n${api.context.plugins.map((plugin, index) => ` ${index + 1}. ${colorText(plugin.name)}`).join("\n")}`
-		});
-		const pluginConfig = await api.callHook("config", {
-			environment: await api.context.getEnvironment(),
-			sequential: true,
-			result: "merge",
-			merge: mergeConfigs
-		});
-		if (isSetObject(pluginConfig)) {
-			api.context.config.pluginConfig = pluginConfig;
-			await api.context.setup();
-		}
-		timer();
+		await api.init();
 		return api;
 	}
 	/**