@powerlines/plugin-vite 0.14.61 → 0.14.63

package/dist/powerlines/src/types/api.d.mts

@@ -0,0 +1,104 @@
+import { ResolvedConfig } from "./resolved.mjs";
+import { BuildInlineConfig, CleanInlineConfig, DeployInlineConfig, DocsInlineConfig, LintInlineConfig, NewInlineConfig, PrepareInlineConfig } from "./config.mjs";
+import { HookKeys, InferHookParameters, InferHookReturnType } from "./hooks.mjs";
+import { APIContext, EnvironmentContext, PluginContext } from "./context.mjs";
+import { CallHookOptions } from "../internal/helpers/hooks.mjs";
+
+//#region ../powerlines/src/types/api.d.ts
+
+/**
+ * Powerlines API Interface
+ */
+interface API<TResolvedConfig extends ResolvedConfig = ResolvedConfig> {
+  /**
+   * The Powerlines shared API context
+   */
+  context: APIContext<TResolvedConfig>;
+  /**
+   * 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
+   */
+  prepare: (inlineConfig: PrepareInlineConfig | NewInlineConfig | CleanInlineConfig | BuildInlineConfig | LintInlineConfig | DocsInlineConfig | DeployInlineConfig) => Promise<void>;
+  /**
+   * 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
+   */
+  new: (inlineConfig: NewInlineConfig) => Promise<void>;
+  /**
+   * 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
+   */
+  clean: (inlineConfig: CleanInlineConfig | PrepareInlineConfig) => Promise<void>;
+  /**
+   * Lint the project source code
+   *
+   * @param inlineConfig - The inline configuration for the lint command
+   * @returns A promise that resolves when the lint command has completed
+   */
+  lint: (inlineConfig: LintInlineConfig) => Promise<void>;
+  /**
+   * 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
+   */
+  build: (inlineConfig: BuildInlineConfig) => Promise<void>;
+  /**
+   * 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
+   */
+  docs: (inlineConfig: DocsInlineConfig) => Promise<void>;
+  /**
+   * 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
+   */
+  deploy: (inlineConfig: DeployInlineConfig) => Promise<void>;
+  /**
+   * 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
+   */
+  finalize: () => Promise<void>;
+  /**
+   * 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
+   */
+  callHook: <TKey extends HookKeys<PluginContext<TResolvedConfig>>>(hook: TKey, options: CallHookOptions & {
+    environment?: string | EnvironmentContext<TResolvedConfig>;
+  }, ...args: InferHookParameters<PluginContext<TResolvedConfig>, TKey>) => Promise<InferHookReturnType<PluginContext<TResolvedConfig>, TKey> | undefined>;
+}
+//#endregion
+export { API };

package/dist/powerlines/src/types/build.d.cts

@@ -1,4 +1,4 @@
-import { UserConfig } from "vite";
+import { DepOptimizationOptions, UserConfig } from "vite";
 
 //#region ../powerlines/src/types/build.d.ts
 
@@ -128,6 +128,12 @@ interface BuildConfig {
    * Should the Powerlines CLI processes skip bundling the `node_modules` directory?
    */
   skipNodeModulesBundle?: boolean;
+  /**
+   * If true, `process.env` referenced in code will be preserved as-is and evaluated in runtime. Otherwise, it is statically replaced as an empty object.
+   *
+   * @defaultValue false
+   */
+  keepProcessEnv?: boolean;
   /**
    * An optional set of override options to apply to the selected build variant.
    *
@@ -137,7 +143,12 @@ interface BuildConfig {
   override?: Record<string, any>;
 }
 type BuildResolvedConfig = Omit<BuildConfig, "override">;
-type ViteBuildConfig = Omit<UserConfig, "entry" | "entryPoints" | "tsconfig" | "tsconfigRaw" | "environments" | "output"> & BuildConfig;
+type ViteBuildConfig = Omit<UserConfig, "entry" | "entryPoints" | "tsconfig" | "tsconfigRaw" | "environments" | "output"> & BuildConfig & {
+  /**
+   * Optimize deps config
+   */
+  optimizeDeps?: Omit<DepOptimizationOptions, "extensions">;
+};
 type ViteResolvedBuildConfig = UserConfig & BuildResolvedConfig;
 //#endregion
 export { BuildConfig, BuildResolvedConfig, UnpluginBuildVariant, ViteBuildConfig, ViteResolvedBuildConfig };

package/dist/powerlines/src/types/build.d.mts

@@ -1,4 +1,4 @@
-import { UserConfig } from "vite";
+import { DepOptimizationOptions, UserConfig } from "vite";
 
 //#region ../powerlines/src/types/build.d.ts
 
@@ -128,6 +128,12 @@ interface BuildConfig {
    * Should the Powerlines CLI processes skip bundling the `node_modules` directory?
    */
   skipNodeModulesBundle?: boolean;
+  /**
+   * If true, `process.env` referenced in code will be preserved as-is and evaluated in runtime. Otherwise, it is statically replaced as an empty object.
+   *
+   * @defaultValue false
+   */
+  keepProcessEnv?: boolean;
   /**
    * An optional set of override options to apply to the selected build variant.
    *
@@ -137,7 +143,12 @@ interface BuildConfig {
   override?: Record<string, any>;
 }
 type BuildResolvedConfig = Omit<BuildConfig, "override">;
-type ViteBuildConfig = Omit<UserConfig, "entry" | "entryPoints" | "tsconfig" | "tsconfigRaw" | "environments" | "output"> & BuildConfig;
+type ViteBuildConfig = Omit<UserConfig, "entry" | "entryPoints" | "tsconfig" | "tsconfigRaw" | "environments" | "output"> & BuildConfig & {
+  /**
+   * Optimize deps config
+   */
+  optimizeDeps?: Omit<DepOptimizationOptions, "extensions">;
+};
 type ViteResolvedBuildConfig = UserConfig & BuildResolvedConfig;
 //#endregion
 export { BuildConfig, BuildResolvedConfig, UnpluginBuildVariant, ViteBuildConfig, ViteResolvedBuildConfig };

package/dist/powerlines/src/types/config.d.cts

@@ -300,6 +300,18 @@ interface CommonUserConfig extends BaseConfig {
    * Environment-specific configurations
    */
   environments?: Record<string, EnvironmentConfig>;
+  /**
+   * Should a single `build` process be ran for each environment?
+   *
+   * @remarks
+   * This option determines how environments are managed during the `build` process. The available options are:
+   *
+   * - `false`: A separate build is ran for each environment.
+   * - `true`: A single build is ran for all environments.
+   *
+   * @defaultValue false
+   */
+  singleBuild?: boolean;
   /**
    * A string identifier that allows a child framework or tool to identify itself when using Powerlines.
    *
@@ -342,5 +354,51 @@ type InlineConfig<TUserConfig extends UserConfig$1 = UserConfig$1> = Partial<TUs
    */
   command: PowerlinesCommand;
 };
+type NewInlineConfig<TUserConfig extends UserConfig$1 = UserConfig$1> = InlineConfig<TUserConfig> & Required<Pick<InlineConfig<TUserConfig>, "root">> & {
+  /**
+   * A string identifier for the Powerlines command being executed
+   */
+  command: "new";
+  /**
+   * The package name (from the \`package.json\`) for the project that will be used in the \`new\` command to create a new project based on this configuration
+   */
+  packageName?: string;
+};
+type CleanInlineConfig<TUserConfig extends UserConfig$1 = UserConfig$1> = InlineConfig<TUserConfig> & {
+  /**
+   * A string identifier for the Powerlines command being executed
+   */
+  command: "clean";
+};
+type PrepareInlineConfig<TUserConfig extends UserConfig$1 = UserConfig$1> = InlineConfig<TUserConfig> & {
+  /**
+   * A string identifier for the Powerlines command being executed
+   */
+  command: "prepare";
+};
+type BuildInlineConfig<TUserConfig extends UserConfig$1 = UserConfig$1> = InlineConfig<TUserConfig> & {
+  /**
+   * A string identifier for the Powerlines command being executed
+   */
+  command: "build";
+};
+type LintInlineConfig<TUserConfig extends UserConfig$1 = UserConfig$1> = InlineConfig<TUserConfig> & {
+  /**
+   * A string identifier for the Powerlines command being executed
+   */
+  command: "lint";
+};
+type DocsInlineConfig<TUserConfig extends UserConfig$1 = UserConfig$1> = InlineConfig<TUserConfig> & {
+  /**
+   * A string identifier for the Powerlines command being executed
+   */
+  command: "docs";
+};
+type DeployInlineConfig<TUserConfig extends UserConfig$1 = UserConfig$1> = InlineConfig<TUserConfig> & {
+  /**
+   * A string identifier for the Powerlines command being executed
+   */
+  command: "deploy";
+};
 //#endregion
-export { EnvironmentConfig, InlineConfig, LogFn, OutputConfig, PluginConfig, UserConfig$1 as UserConfig, ViteUserConfig, WorkspaceConfig };
+export { BuildInlineConfig, CleanInlineConfig, DeployInlineConfig, DocsInlineConfig, EnvironmentConfig, InlineConfig, LintInlineConfig, LogFn, NewInlineConfig, OutputConfig, PluginConfig, PrepareInlineConfig, UserConfig$1 as UserConfig, ViteUserConfig, WorkspaceConfig };

package/dist/powerlines/src/types/config.d.mts

@@ -5,9 +5,9 @@ import { Plugin } from "./plugin.mjs";
 import { TSConfig } from "./tsconfig.mjs";
 import { PluginContext } from "./context.mjs";
 import { LogLevelLabel } from "@storm-software/config-tools/types";
+import { PreviewOptions } from "vite";
 import { transformAsync } from "@babel/core";
 import "c12";
-import { PreviewOptions } from "vite";
 import { MaybePromise } from "@stryke/types/base";
 import { Format } from "@storm-software/build-tools/types";
 import { StormWorkspaceConfig } from "@storm-software/config/types";
@@ -302,6 +302,18 @@ interface CommonUserConfig extends BaseConfig {
    * Environment-specific configurations
    */
   environments?: Record<string, EnvironmentConfig>;
+  /**
+   * Should a single `build` process be ran for each environment?
+   *
+   * @remarks
+   * This option determines how environments are managed during the `build` process. The available options are:
+   *
+   * - `false`: A separate build is ran for each environment.
+   * - `true`: A single build is ran for all environments.
+   *
+   * @defaultValue false
+   */
+  singleBuild?: boolean;
   /**
    * A string identifier that allows a child framework or tool to identify itself when using Powerlines.
    *
@@ -344,5 +356,51 @@ type InlineConfig<TUserConfig extends UserConfig$1 = UserConfig$1> = Partial<TUs
    */
   command: PowerlinesCommand;
 };
+type NewInlineConfig<TUserConfig extends UserConfig$1 = UserConfig$1> = InlineConfig<TUserConfig> & Required<Pick<InlineConfig<TUserConfig>, "root">> & {
+  /**
+   * A string identifier for the Powerlines command being executed
+   */
+  command: "new";
+  /**
+   * The package name (from the \`package.json\`) for the project that will be used in the \`new\` command to create a new project based on this configuration
+   */
+  packageName?: string;
+};
+type CleanInlineConfig<TUserConfig extends UserConfig$1 = UserConfig$1> = InlineConfig<TUserConfig> & {
+  /**
+   * A string identifier for the Powerlines command being executed
+   */
+  command: "clean";
+};
+type PrepareInlineConfig<TUserConfig extends UserConfig$1 = UserConfig$1> = InlineConfig<TUserConfig> & {
+  /**
+   * A string identifier for the Powerlines command being executed
+   */
+  command: "prepare";
+};
+type BuildInlineConfig<TUserConfig extends UserConfig$1 = UserConfig$1> = InlineConfig<TUserConfig> & {
+  /**
+   * A string identifier for the Powerlines command being executed
+   */
+  command: "build";
+};
+type LintInlineConfig<TUserConfig extends UserConfig$1 = UserConfig$1> = InlineConfig<TUserConfig> & {
+  /**
+   * A string identifier for the Powerlines command being executed
+   */
+  command: "lint";
+};
+type DocsInlineConfig<TUserConfig extends UserConfig$1 = UserConfig$1> = InlineConfig<TUserConfig> & {
+  /**
+   * A string identifier for the Powerlines command being executed
+   */
+  command: "docs";
+};
+type DeployInlineConfig<TUserConfig extends UserConfig$1 = UserConfig$1> = InlineConfig<TUserConfig> & {
+  /**
+   * A string identifier for the Powerlines command being executed
+   */
+  command: "deploy";
+};
 //#endregion
-export { EnvironmentConfig, InlineConfig, LogFn, OutputConfig, PluginConfig, UserConfig$1 as UserConfig, ViteUserConfig, WorkspaceConfig };
+export { BuildInlineConfig, CleanInlineConfig, DeployInlineConfig, DocsInlineConfig, EnvironmentConfig, InlineConfig, LintInlineConfig, LogFn, NewInlineConfig, OutputConfig, PluginConfig, PrepareInlineConfig, UserConfig$1 as UserConfig, ViteUserConfig, WorkspaceConfig };

package/dist/powerlines/src/types/context.d.cts

@@ -1,7 +1,9 @@
 import { ResolveOptions, VirtualFile, VirtualFileSystemInterface } from "./fs.cjs";
 import { EnvironmentResolvedConfig, ResolvedConfig, ResolvedEntryTypeDefinition } from "./resolved.cjs";
+import { Plugin } from "./plugin.cjs";
 import { ParsedTypeScriptConfig } from "./tsconfig.cjs";
 import { InlineConfig, LogFn, UserConfig, WorkspaceConfig } from "./config.cjs";
+import { HookKeys, Hooks, HooksList } from "./hooks.cjs";
 import { EnvPaths } from "@stryke/env/get-env-paths";
 import { FetchRequestOptions } from "@stryke/http/fetch";
 import { NonUndefined } from "@stryke/types/base";
@@ -49,6 +51,9 @@ interface TransformResult$1 {
   code: string;
   map: SourceMap | null;
 }
+interface SelectHooksOptions {
+  order?: "pre" | "post" | "normal";
+}
 interface InitContextOptions {
   /**
    * If false, the plugin will be loaded after all other plugins.
@@ -329,6 +334,112 @@ type Context<TResolvedConfig extends ResolvedConfig = ResolvedConfig> = Omit<Unr
    */
   config: TResolvedConfig;
 };
+interface APIContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig> {
+  /**
+   * The expected plugins options for the Powerlines project.
+   *
+   * @remarks
+   * This is a record of plugin identifiers to their respective options. This field is populated by the Powerlines engine during both plugin initialization and the `init` command.
+   */
+  plugins: Plugin<PluginContext<TResolvedConfig>>[];
+  /**
+   * A function to add a plugin to the context and update the configuration options
+   */
+  addPlugin: (plugin: Plugin<PluginContext<TResolvedConfig>>) => Promise<void>;
+  /**
+   * A table for storing the current context for each configured environment
+   */
+  environments: Record<string, EnvironmentContext<TResolvedConfig>>;
+  /**
+   * Retrieves the context for a specific environment by name
+   *
+   * @throws Will throw an error if the environment does not exist
+   *
+   * @param name - The name of the environment to retrieve. If not provided, the default environment is returned.
+   * @returns A promise that resolves to the environment context.
+   *
+   * @example
+   * ```ts
+   * const devEnv = await apiContext.getEnvironment("development");
+   * const defaultEnv = await apiContext.getEnvironment();
+   * ```
+   */
+  getEnvironment: (name?: string) => Promise<EnvironmentContext<TResolvedConfig>>;
+  /**
+   * Safely retrieves the context for a specific environment by name
+   *
+   * @param name - The name of the environment to retrieve. If not provided, the default environment is returned.
+   * @returns A promise that resolves to the environment context, or undefined if the environment does not exist.
+   *
+   * @example
+   * ```ts
+   * const devEnv = await apiContext.getEnvironmentSafe("development");
+   * const defaultEnv = await apiContext.getEnvironmentSafe();
+   * ```
+   *
+   * @remarks
+   * This method is similar to `getEnvironment`, but it returns `undefined` instead of throwing an error if the specified environment does not exist.
+   * This can be useful in scenarios where the existence of an environment is optional or uncertain.
+   *
+   * ```ts
+   * const testEnv = await apiContext.getEnvironmentSafe("test");
+   * if (testEnv) {
+   *   // Environment exists, safe to use it
+   * } else {
+   *   // Environment does not exist, handle accordingly
+   * }
+   * ```
+   *
+   * Using this method helps avoid unhandled exceptions in cases where an environment might not be defined.
+   */
+  getEnvironmentSafe: (name?: string) => Promise<EnvironmentContext<TResolvedConfig> | undefined>;
+  /**
+   * A function to copy the context and update the fields for a specific environment
+   *
+   * @param environment - The environment configuration to use.
+   * @returns A new context instance with the updated environment.
+   */
+  in: (environment: EnvironmentResolvedConfig) => Promise<EnvironmentContext<TResolvedConfig>>;
+  /**
+   * A function to merge all configured environments into a single context
+   *
+   * @returns A promise that resolves to the merged environment context.
+   */
+  toEnvironment: () => Promise<EnvironmentContext<TResolvedConfig>>;
+}
+interface EnvironmentContextPlugin<TResolvedConfig extends ResolvedConfig = ResolvedConfig> {
+  plugin: Plugin<PluginContext<TResolvedConfig>>;
+  context: PluginContext<TResolvedConfig>;
+}
+interface SelectHooksResult<TResolvedConfig extends ResolvedConfig, TKey extends HookKeys<PluginContext<TResolvedConfig>>> {
+  handle: Hooks[TKey];
+  context: PluginContext<TResolvedConfig>;
+}
+interface EnvironmentContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig> {
+  /**
+   * The expected plugins options for the Powerlines project.
+   *
+   * @remarks
+   * This is a record of plugin identifiers to their respective options. This field is populated by the Powerlines engine during both plugin initialization and the `init` command.
+   */
+  plugins: EnvironmentContextPlugin<TResolvedConfig>[];
+  /**
+   * A function to add a plugin to the context and update the configuration options
+   */
+  addPlugin: (plugin: Plugin<PluginContext<TResolvedConfig>>) => Promise<void>;
+  /**
+   * The environment specific resolved configuration
+   */
+  environment: EnvironmentResolvedConfig;
+  /**
+   * A table holding references to hook functions registered by plugins
+   */
+  hooks: HooksList<PluginContext<TResolvedConfig>>;
+  /**
+   * Retrieves the hook handlers for a specific hook name
+   */
+  selectHooks: <TKey extends HookKeys<PluginContext<TResolvedConfig>>>(hook: TKey, options?: SelectHooksOptions) => SelectHooksResult<TResolvedConfig, TKey>[];
+}
 interface PluginContext<out TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig>, UnpluginContext {
   /**
    * The environment specific resolved configuration
@@ -344,4 +455,4 @@ interface PluginContext<out TResolvedConfig extends ResolvedConfig = ResolvedCon
 }
 type BuildPluginContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> = UnpluginBuildContext & PluginContext<TResolvedConfig>;
 //#endregion
-export { BuildPluginContext, PluginContext, UnresolvedContext };
+export { APIContext, BuildPluginContext, EnvironmentContext, PluginContext, SelectHooksOptions, UnresolvedContext };

package/dist/powerlines/src/types/context.d.mts

@@ -1,9 +1,9 @@
 import { ResolveOptions, VirtualFile, VirtualFileSystemInterface } from "./fs.mjs";
 import { EnvironmentResolvedConfig, ResolvedConfig, ResolvedEntryTypeDefinition } from "./resolved.mjs";
-import "./plugin.mjs";
+import { Plugin } from "./plugin.mjs";
 import { ParsedTypeScriptConfig } from "./tsconfig.mjs";
 import { InlineConfig, LogFn, UserConfig, WorkspaceConfig } from "./config.mjs";
-import "./hooks.mjs";
+import { HookKeys, Hooks, HooksList } from "./hooks.mjs";
 import { ExternalIdResult, UnpluginBuildContext, UnpluginContext, UnpluginMessage } from "unplugin";
 import { Project } from "ts-morph";
 import { EnvPaths } from "@stryke/env/get-env-paths";
@@ -51,6 +51,9 @@ interface TransformResult$1 {
   code: string;
   map: SourceMap | null;
 }
+interface SelectHooksOptions {
+  order?: "pre" | "post" | "normal";
+}
 interface InitContextOptions {
   /**
    * If false, the plugin will be loaded after all other plugins.
@@ -331,6 +334,112 @@ type Context<TResolvedConfig extends ResolvedConfig = ResolvedConfig> = Omit<Unr
    */
   config: TResolvedConfig;
 };
+interface APIContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig> {
+  /**
+   * The expected plugins options for the Powerlines project.
+   *
+   * @remarks
+   * This is a record of plugin identifiers to their respective options. This field is populated by the Powerlines engine during both plugin initialization and the `init` command.
+   */
+  plugins: Plugin<PluginContext<TResolvedConfig>>[];
+  /**
+   * A function to add a plugin to the context and update the configuration options
+   */
+  addPlugin: (plugin: Plugin<PluginContext<TResolvedConfig>>) => Promise<void>;
+  /**
+   * A table for storing the current context for each configured environment
+   */
+  environments: Record<string, EnvironmentContext<TResolvedConfig>>;
+  /**
+   * Retrieves the context for a specific environment by name
+   *
+   * @throws Will throw an error if the environment does not exist
+   *
+   * @param name - The name of the environment to retrieve. If not provided, the default environment is returned.
+   * @returns A promise that resolves to the environment context.
+   *
+   * @example
+   * ```ts
+   * const devEnv = await apiContext.getEnvironment("development");
+   * const defaultEnv = await apiContext.getEnvironment();
+   * ```
+   */
+  getEnvironment: (name?: string) => Promise<EnvironmentContext<TResolvedConfig>>;
+  /**
+   * Safely retrieves the context for a specific environment by name
+   *
+   * @param name - The name of the environment to retrieve. If not provided, the default environment is returned.
+   * @returns A promise that resolves to the environment context, or undefined if the environment does not exist.
+   *
+   * @example
+   * ```ts
+   * const devEnv = await apiContext.getEnvironmentSafe("development");
+   * const defaultEnv = await apiContext.getEnvironmentSafe();
+   * ```
+   *
+   * @remarks
+   * This method is similar to `getEnvironment`, but it returns `undefined` instead of throwing an error if the specified environment does not exist.
+   * This can be useful in scenarios where the existence of an environment is optional or uncertain.
+   *
+   * ```ts
+   * const testEnv = await apiContext.getEnvironmentSafe("test");
+   * if (testEnv) {
+   *   // Environment exists, safe to use it
+   * } else {
+   *   // Environment does not exist, handle accordingly
+   * }
+   * ```
+   *
+   * Using this method helps avoid unhandled exceptions in cases where an environment might not be defined.
+   */
+  getEnvironmentSafe: (name?: string) => Promise<EnvironmentContext<TResolvedConfig> | undefined>;
+  /**
+   * A function to copy the context and update the fields for a specific environment
+   *
+   * @param environment - The environment configuration to use.
+   * @returns A new context instance with the updated environment.
+   */
+  in: (environment: EnvironmentResolvedConfig) => Promise<EnvironmentContext<TResolvedConfig>>;
+  /**
+   * A function to merge all configured environments into a single context
+   *
+   * @returns A promise that resolves to the merged environment context.
+   */
+  toEnvironment: () => Promise<EnvironmentContext<TResolvedConfig>>;
+}
+interface EnvironmentContextPlugin<TResolvedConfig extends ResolvedConfig = ResolvedConfig> {
+  plugin: Plugin<PluginContext<TResolvedConfig>>;
+  context: PluginContext<TResolvedConfig>;
+}
+interface SelectHooksResult<TResolvedConfig extends ResolvedConfig, TKey extends HookKeys<PluginContext<TResolvedConfig>>> {
+  handle: Hooks[TKey];
+  context: PluginContext<TResolvedConfig>;
+}
+interface EnvironmentContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig> {
+  /**
+   * The expected plugins options for the Powerlines project.
+   *
+   * @remarks
+   * This is a record of plugin identifiers to their respective options. This field is populated by the Powerlines engine during both plugin initialization and the `init` command.
+   */
+  plugins: EnvironmentContextPlugin<TResolvedConfig>[];
+  /**
+   * A function to add a plugin to the context and update the configuration options
+   */
+  addPlugin: (plugin: Plugin<PluginContext<TResolvedConfig>>) => Promise<void>;
+  /**
+   * The environment specific resolved configuration
+   */
+  environment: EnvironmentResolvedConfig;
+  /**
+   * A table holding references to hook functions registered by plugins
+   */
+  hooks: HooksList<PluginContext<TResolvedConfig>>;
+  /**
+   * Retrieves the hook handlers for a specific hook name
+   */
+  selectHooks: <TKey extends HookKeys<PluginContext<TResolvedConfig>>>(hook: TKey, options?: SelectHooksOptions) => SelectHooksResult<TResolvedConfig, TKey>[];
+}
 interface PluginContext<out TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig>, UnpluginContext {
   /**
    * The environment specific resolved configuration
@@ -346,4 +455,4 @@ interface PluginContext<out TResolvedConfig extends ResolvedConfig = ResolvedCon
 }
 type BuildPluginContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> = UnpluginBuildContext & PluginContext<TResolvedConfig>;
 //#endregion
-export { BuildPluginContext, PluginContext, UnresolvedContext };
+export { APIContext, BuildPluginContext, EnvironmentContext, PluginContext, SelectHooksOptions, UnresolvedContext };

package/dist/powerlines/src/types/hooks.d.cts

@@ -0,0 +1,30 @@
+import { BasePluginHookFunctions, ExternalPluginHookFunctions, Plugin, PluginHookFunctions, PluginHookObject } from "./plugin.cjs";
+import { PluginContext } from "./context.cjs";
+
+//#region ../powerlines/src/types/hooks.d.ts
+type BaseHooks<TContext extends PluginContext = PluginContext> = BasePluginHookFunctions<TContext>;
+type BaseHookKeys<TContext extends PluginContext = PluginContext> = keyof BaseHooks<TContext>;
+type ExternalHooks<TContext extends PluginContext = PluginContext> = ExternalPluginHookFunctions<TContext>;
+type ExternalHookKeys<TContext extends PluginContext = PluginContext> = keyof ExternalHooks<TContext>;
+type Hooks<TContext extends PluginContext = PluginContext> = PluginHookFunctions<TContext>;
+type HookKeys<TContext extends PluginContext = PluginContext> = keyof Hooks<TContext>;
+interface BaseHooksListItem<TContext extends PluginContext = PluginContext, TKey$1 extends BaseHookKeys<TContext> = BaseHookKeys<TContext>> extends PluginHookObject<BaseHooks<TContext>[TKey$1]> {
+  plugin: Plugin<TContext>;
+}
+interface BaseHooksList<TContext extends PluginContext = PluginContext, TKey$1 extends BaseHookKeys<TContext> = BaseHookKeys<TContext>> {
+  preOrdered?: BaseHooksListItem<TContext, TKey$1>[];
+  preEnforced?: BaseHooksListItem<TContext, TKey$1>[];
+  normal?: BaseHooksListItem<TContext, TKey$1>[];
+  postEnforced?: BaseHooksListItem<TContext, TKey$1>[];
+  postOrdered?: BaseHooksListItem<TContext, TKey$1>[];
+}
+interface ExternalHooksListItem<TContext extends PluginContext = PluginContext, TKey$1 extends ExternalHookKeys<TContext> = ExternalHookKeys<TContext>> {
+  plugin: Plugin<TContext>;
+  handler: ExternalHooks<TContext>[TKey$1];
+}
+type HooksList<TContext extends PluginContext = PluginContext> = { [TKey in BaseHookKeys<TContext>]?: BaseHooksList<TContext, TKey> } & { [TKey in ExternalHookKeys<TContext>]?: ExternalHooksListItem<TContext, TKey>[] };
+type InferHookHandler<TContext extends PluginContext, TKey$1 extends HookKeys<TContext>> = Hooks<TContext>[TKey$1];
+type InferHookReturnType<TContext extends PluginContext, TKey$1 extends HookKeys<TContext>> = ReturnType<InferHookHandler<TContext, TKey$1>> extends Promise<infer U> ? U extends Promise<infer V> ? V : U : ReturnType<InferHookHandler<TContext, TKey$1>>;
+type InferHookParameters<TContext extends PluginContext, TKey$1 extends HookKeys<TContext>> = Parameters<InferHookHandler<TContext, TKey$1>>;
+//#endregion
+export { HookKeys, Hooks, HooksList, InferHookParameters, InferHookReturnType };

package/dist/powerlines/src/types/hooks.d.mts

@@ -1,2 +1,30 @@
-import "./plugin.mjs";
-import "./context.mjs";
+import { BasePluginHookFunctions, ExternalPluginHookFunctions, Plugin, PluginHookFunctions, PluginHookObject } from "./plugin.mjs";
+import { PluginContext } from "./context.mjs";
+
+//#region ../powerlines/src/types/hooks.d.ts
+type BaseHooks<TContext extends PluginContext = PluginContext> = BasePluginHookFunctions<TContext>;
+type BaseHookKeys<TContext extends PluginContext = PluginContext> = keyof BaseHooks<TContext>;
+type ExternalHooks<TContext extends PluginContext = PluginContext> = ExternalPluginHookFunctions<TContext>;
+type ExternalHookKeys<TContext extends PluginContext = PluginContext> = keyof ExternalHooks<TContext>;
+type Hooks<TContext extends PluginContext = PluginContext> = PluginHookFunctions<TContext>;
+type HookKeys<TContext extends PluginContext = PluginContext> = keyof Hooks<TContext>;
+interface BaseHooksListItem<TContext extends PluginContext = PluginContext, TKey$1 extends BaseHookKeys<TContext> = BaseHookKeys<TContext>> extends PluginHookObject<BaseHooks<TContext>[TKey$1]> {
+  plugin: Plugin<TContext>;
+}
+interface BaseHooksList<TContext extends PluginContext = PluginContext, TKey$1 extends BaseHookKeys<TContext> = BaseHookKeys<TContext>> {
+  preOrdered?: BaseHooksListItem<TContext, TKey$1>[];
+  preEnforced?: BaseHooksListItem<TContext, TKey$1>[];
+  normal?: BaseHooksListItem<TContext, TKey$1>[];
+  postEnforced?: BaseHooksListItem<TContext, TKey$1>[];
+  postOrdered?: BaseHooksListItem<TContext, TKey$1>[];
+}
+interface ExternalHooksListItem<TContext extends PluginContext = PluginContext, TKey$1 extends ExternalHookKeys<TContext> = ExternalHookKeys<TContext>> {
+  plugin: Plugin<TContext>;
+  handler: ExternalHooks<TContext>[TKey$1];
+}
+type HooksList<TContext extends PluginContext = PluginContext> = { [TKey in BaseHookKeys<TContext>]?: BaseHooksList<TContext, TKey> } & { [TKey in ExternalHookKeys<TContext>]?: ExternalHooksListItem<TContext, TKey>[] };
+type InferHookHandler<TContext extends PluginContext, TKey$1 extends HookKeys<TContext>> = Hooks<TContext>[TKey$1];
+type InferHookReturnType<TContext extends PluginContext, TKey$1 extends HookKeys<TContext>> = ReturnType<InferHookHandler<TContext, TKey$1>> extends Promise<infer U> ? U extends Promise<infer V> ? V : U : ReturnType<InferHookHandler<TContext, TKey$1>>;
+type InferHookParameters<TContext extends PluginContext, TKey$1 extends HookKeys<TContext>> = Parameters<InferHookHandler<TContext, TKey$1>>;
+//#endregion
+export { HookKeys, Hooks, HooksList, InferHookParameters, InferHookReturnType };