@powerlines/plugin-alloy 0.18.7 → 0.18.8

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

@@ -1,6 +1,18 @@
-//#region ../powerlines/src/types/build.d.ts
+import { DepOptimizationOptions, UserConfig } from "vite";
+import { UserConfig as UserConfig$1 } from "@farmfe/core";
+import { Configuration } from "@rspack/core";
+import { BuildOptions } from "@storm-software/tsup/types";
+import { UnbuildOptions } from "@storm-software/unbuild/types";
+import { BuildOptions as BuildOptions$1 } from "esbuild";
+import { RolldownOptions } from "rolldown";
+import { OutputOptions, RollupOptions } from "rollup";
+import { UserConfig as UserConfig$2 } from "tsdown";
+import { Configuration as Configuration$1 } from "webpack";
 
-type UnpluginBuildVariant = "rollup" | "webpack" | "rspack" | "vite" | "esbuild" | "farm" | "unloader" | "rolldown";
+//#region ../powerlines/src/types/build.d.ts
+type UnpluginBuilderVariant = "rollup" | "webpack" | "rspack" | "vite" | "esbuild" | "farm" | "unloader" | "rolldown" | "bun";
+type BuilderVariant = UnpluginBuilderVariant | "tsup" | "tsdown" | "unbuild";
+type InferUnpluginVariant<TBuildVariant extends BuilderVariant> = TBuildVariant extends "tsup" ? "esbuild" : TBuildVariant extends "tsdown" ? "rolldown" : TBuildVariant extends "unbuild" ? "rollup" : TBuildVariant;
 interface BuildConfig {
   /**
    * The platform to build the project for
@@ -141,5 +153,33 @@ interface BuildConfig {
   override?: Record<string, any>;
 }
 type BuildResolvedConfig = Omit<BuildConfig, "override">;
+type ESBuildBuildConfig = Omit<BuildOptions$1, "entryPoints" | "sourceRoot" | "platform" | "outdir" | "env" | "assets" | "external" | "inject" | "tsconfig" | "tsconfigRaw" | "logLevel"> & BuildConfig;
+type ESBuildResolvedBuildConfig = Omit<BuildOptions$1, "inject"> & BuildResolvedConfig;
+type ViteBuildConfig = Omit<UserConfig, "entry" | "entryPoints" | "tsconfig" | "tsconfigRaw" | "environments" | "output"> & BuildConfig & {
+  /**
+   * Optimize deps config
+   */
+  optimizeDeps?: Omit<DepOptimizationOptions, "extensions">;
+};
+type ViteResolvedBuildConfig = UserConfig & BuildResolvedConfig;
+type WebpackBuildConfig = Omit<Configuration$1, "name" | "entry" | "entryPoints" | "tsconfig" | "tsconfigRaw"> & BuildConfig;
+type WebpackResolvedBuildConfig = Configuration$1 & BuildResolvedConfig;
+type RspackBuildConfig = Omit<Configuration, "name" | "entry" | "entryPoints" | "tsconfig" | "tsconfigRaw"> & BuildConfig;
+type RspackResolvedBuildConfig = Configuration & BuildResolvedConfig;
+type RollupBuildOutputConfig = Omit<OutputOptions, "dir" | "format">;
+type RollupBuildConfig = Omit<RollupOptions, "entry" | "external" | "input" | "output" | "logLevel"> & {
+  output: RollupBuildOutputConfig | RollupBuildOutputConfig[];
+} & BuildConfig;
+type RollupResolvedBuildConfig = RollupOptions & BuildResolvedConfig;
+type RolldownBuildConfig = Omit<RolldownOptions, "input" | "external" | "tsconfig" | "logLevel" | "output"> & BuildConfig;
+type RolldownResolvedBuildConfig = RolldownOptions & BuildResolvedConfig;
+type TsupBuildConfig = Partial<Omit<BuildOptions, "userOptions" | "tsconfig" | "tsconfigRaw" | "assets" | "outputPath" | "mode" | "format" | "platform" | "projectRoot" | "clean" | "env" | "entry" | "entryPoints" | "external" | "noExternal" | "skipNodeModulesBundle">> & BuildConfig;
+type TsupResolvedBuildConfig = BuildOptions & BuildResolvedConfig;
+type TsdownBuildConfig = Partial<Omit<UserConfig$2, "name" | "outDir" | "clean" | "cwd" | "tsconfig" | "publicDir" | "copy" | "alias" | "format" | "platform" | "env" | "define" | "entry" | "external" | "noExternal" | "skipNodeModulesBundle">> & BuildConfig;
+type TsdownResolvedBuildConfig = UserConfig$2 & BuildResolvedConfig;
+type UnbuildBuildConfig = Partial<Omit<UnbuildOptions, "tsconfig" | "tsconfigRaw" | "assets" | "outputPath" | "mode" | "format" | "platform" | "projectRoot" | "env" | "entry" | "entryPoints">> & BuildConfig;
+type UnbuildResolvedBuildConfig = UnbuildOptions & BuildResolvedConfig;
+type FarmBuildConfig = Partial<Omit<UserConfig$1, "tsconfig" | "tsconfigRaw" | "assets" | "outputPath" | "mode" | "format" | "platform" | "projectRoot" | "env" | "entry" | "entryPoints">> & BuildConfig;
+type FarmResolvedBuildConfig = UserConfig$1 & BuildResolvedConfig;
 //#endregion
-export { BuildConfig, BuildResolvedConfig, UnpluginBuildVariant };
+export { BuildConfig, BuildResolvedConfig, BuilderVariant, ESBuildBuildConfig, ESBuildResolvedBuildConfig, FarmBuildConfig, FarmResolvedBuildConfig, InferUnpluginVariant, RolldownBuildConfig, RolldownResolvedBuildConfig, RollupBuildConfig, RollupResolvedBuildConfig, RspackBuildConfig, RspackResolvedBuildConfig, TsdownBuildConfig, TsdownResolvedBuildConfig, TsupBuildConfig, TsupResolvedBuildConfig, UnbuildBuildConfig, UnbuildResolvedBuildConfig, UnpluginBuilderVariant, ViteBuildConfig, ViteResolvedBuildConfig, WebpackBuildConfig, WebpackResolvedBuildConfig };

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

@@ -1,4 +1,4 @@
-import { BuildConfig, BuildResolvedConfig } from "./build.cjs";
+import { BuildConfig, BuildResolvedConfig, ESBuildBuildConfig, ESBuildResolvedBuildConfig, FarmBuildConfig, FarmResolvedBuildConfig, RolldownBuildConfig, RolldownResolvedBuildConfig, RollupBuildConfig, RollupResolvedBuildConfig, RspackBuildConfig, RspackResolvedBuildConfig, TsdownBuildConfig, TsdownResolvedBuildConfig, TsupBuildConfig, TsupResolvedBuildConfig, UnbuildBuildConfig, UnbuildResolvedBuildConfig, ViteBuildConfig, ViteResolvedBuildConfig, WebpackBuildConfig, WebpackResolvedBuildConfig } from "./build.cjs";
 import { StoragePort, StoragePreset } from "./fs.cjs";
 import { Plugin } from "./plugin.cjs";
 import { TSConfig } from "./tsconfig.cjs";
@@ -341,7 +341,7 @@ interface CommonUserConfig extends BaseConfig {
    */
   framework?: string;
 }
-interface UserConfig<TBuildConfig extends BuildConfig = BuildConfig, TBuildResolvedConfig extends BuildResolvedConfig = BuildResolvedConfig, TBuildVariant extends string = any> extends Omit<CommonUserConfig, "build"> {
+interface UserConfig$1<TBuildConfig extends BuildConfig = BuildConfig, TBuildResolvedConfig extends BuildResolvedConfig = BuildResolvedConfig, TBuildVariant extends string = any> extends Omit<CommonUserConfig, "build"> {
   /**
    * Configuration provided to build processes
    *
@@ -362,15 +362,71 @@ interface UserConfig<TBuildConfig extends BuildConfig = BuildConfig, TBuildResol
     override?: Partial<TBuildResolvedConfig>;
   };
 }
+type WebpackUserConfig = UserConfig$1<WebpackBuildConfig, WebpackResolvedBuildConfig, "webpack">;
+type RspackUserConfig = UserConfig$1<RspackBuildConfig, RspackResolvedBuildConfig, "rspack">;
+type RollupUserConfig = UserConfig$1<RollupBuildConfig, RollupResolvedBuildConfig, "rollup">;
+type RolldownUserConfig = UserConfig$1<RolldownBuildConfig, RolldownResolvedBuildConfig, "rolldown">;
+type ViteUserConfig = UserConfig$1<ViteBuildConfig, ViteResolvedBuildConfig, "vite">;
+type ESBuildUserConfig = UserConfig$1<ESBuildBuildConfig, ESBuildResolvedBuildConfig, "esbuild">;
+type UnbuildUserConfig = UserConfig$1<UnbuildBuildConfig, UnbuildResolvedBuildConfig, "unbuild">;
+type TsupUserConfig = UserConfig$1<TsupBuildConfig, TsupResolvedBuildConfig, "tsup">;
+type TsdownUserConfig = UserConfig$1<TsdownBuildConfig, TsdownResolvedBuildConfig, "tsdown">;
+type FarmUserConfig = UserConfig$1<FarmBuildConfig, FarmResolvedBuildConfig, "farm">;
 type PowerlinesCommand = "new" | "prepare" | "build" | "lint" | "test" | "docs" | "deploy" | "clean";
 /**
  * The configuration provided while executing Powerlines commands.
  */
-type InlineConfig<TUserConfig extends UserConfig = UserConfig> = Partial<TUserConfig> & {
+type InlineConfig<TUserConfig extends UserConfig$1 = UserConfig$1> = Partial<TUserConfig> & {
   /**
    * A string identifier for the Powerlines command being executed
    */
   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, WorkspaceConfig };
+export { BuildInlineConfig, CleanInlineConfig, DeployInlineConfig, DocsInlineConfig, ESBuildUserConfig, EnvironmentConfig, FarmUserConfig, InlineConfig, LintInlineConfig, LogFn, NewInlineConfig, OutputConfig, PluginConfig, PrepareInlineConfig, RolldownUserConfig, RollupUserConfig, RspackUserConfig, TsdownUserConfig, TsupUserConfig, UnbuildUserConfig, UserConfig$1 as UserConfig, ViteUserConfig, WebpackUserConfig, WorkspaceConfig };

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

@@ -1,4 +1,4 @@
-import { BuildConfig, BuildResolvedConfig } from "./build.mjs";
+import { BuildConfig, BuildResolvedConfig, ESBuildBuildConfig, ESBuildResolvedBuildConfig, FarmBuildConfig, FarmResolvedBuildConfig, RolldownBuildConfig, RolldownResolvedBuildConfig, RollupBuildConfig, RollupResolvedBuildConfig, RspackBuildConfig, RspackResolvedBuildConfig, TsdownBuildConfig, TsdownResolvedBuildConfig, TsupBuildConfig, TsupResolvedBuildConfig, UnbuildBuildConfig, UnbuildResolvedBuildConfig, ViteBuildConfig, ViteResolvedBuildConfig, WebpackBuildConfig, WebpackResolvedBuildConfig } from "./build.mjs";
 import { StoragePort, StoragePreset } from "./fs.mjs";
 import { Plugin } from "./plugin.mjs";
 import { TSConfig } from "./tsconfig.mjs";
@@ -341,7 +341,7 @@ interface CommonUserConfig extends BaseConfig {
    */
   framework?: string;
 }
-interface UserConfig<TBuildConfig extends BuildConfig = BuildConfig, TBuildResolvedConfig extends BuildResolvedConfig = BuildResolvedConfig, TBuildVariant extends string = any> extends Omit<CommonUserConfig, "build"> {
+interface UserConfig$1<TBuildConfig extends BuildConfig = BuildConfig, TBuildResolvedConfig extends BuildResolvedConfig = BuildResolvedConfig, TBuildVariant extends string = any> extends Omit<CommonUserConfig, "build"> {
   /**
    * Configuration provided to build processes
    *
@@ -362,15 +362,71 @@ interface UserConfig<TBuildConfig extends BuildConfig = BuildConfig, TBuildResol
     override?: Partial<TBuildResolvedConfig>;
   };
 }
+type WebpackUserConfig = UserConfig$1<WebpackBuildConfig, WebpackResolvedBuildConfig, "webpack">;
+type RspackUserConfig = UserConfig$1<RspackBuildConfig, RspackResolvedBuildConfig, "rspack">;
+type RollupUserConfig = UserConfig$1<RollupBuildConfig, RollupResolvedBuildConfig, "rollup">;
+type RolldownUserConfig = UserConfig$1<RolldownBuildConfig, RolldownResolvedBuildConfig, "rolldown">;
+type ViteUserConfig = UserConfig$1<ViteBuildConfig, ViteResolvedBuildConfig, "vite">;
+type ESBuildUserConfig = UserConfig$1<ESBuildBuildConfig, ESBuildResolvedBuildConfig, "esbuild">;
+type UnbuildUserConfig = UserConfig$1<UnbuildBuildConfig, UnbuildResolvedBuildConfig, "unbuild">;
+type TsupUserConfig = UserConfig$1<TsupBuildConfig, TsupResolvedBuildConfig, "tsup">;
+type TsdownUserConfig = UserConfig$1<TsdownBuildConfig, TsdownResolvedBuildConfig, "tsdown">;
+type FarmUserConfig = UserConfig$1<FarmBuildConfig, FarmResolvedBuildConfig, "farm">;
 type PowerlinesCommand = "new" | "prepare" | "build" | "lint" | "test" | "docs" | "deploy" | "clean";
 /**
  * The configuration provided while executing Powerlines commands.
  */
-type InlineConfig<TUserConfig extends UserConfig = UserConfig> = Partial<TUserConfig> & {
+type InlineConfig<TUserConfig extends UserConfig$1 = UserConfig$1> = Partial<TUserConfig> & {
   /**
    * A string identifier for the Powerlines command being executed
    */
   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, WorkspaceConfig };
+export { BuildInlineConfig, CleanInlineConfig, DeployInlineConfig, DocsInlineConfig, ESBuildUserConfig, EnvironmentConfig, FarmUserConfig, InlineConfig, LintInlineConfig, LogFn, NewInlineConfig, OutputConfig, PluginConfig, PrepareInlineConfig, RolldownUserConfig, RollupUserConfig, RspackUserConfig, TsdownUserConfig, TsupUserConfig, UnbuildUserConfig, UserConfig$1 as UserConfig, ViteUserConfig, WebpackUserConfig, WorkspaceConfig };

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

@@ -1,5 +1,7 @@
 import { ResolveOptions, VirtualFile, VirtualFileSystemInterface, WriteOptions } from "./fs.cjs";
 import { EnvironmentResolvedConfig, ResolvedConfig, ResolvedEntryTypeDefinition } from "./resolved.cjs";
+import { HooksList, InferHooksListItem } from "./hooks.cjs";
+import { Plugin } from "./plugin.cjs";
 import { ParsedTypeScriptConfig } from "./tsconfig.cjs";
 import { InlineConfig, LogFn, UserConfig, WorkspaceConfig } from "./config.cjs";
 import { EnvPaths } from "@stryke/env/get-env-paths";
@@ -49,6 +51,9 @@ interface TransformResult$1 {
   code: string;
   map: SourceMap | null;
 }
+interface SelectHooksOptions {
+  order?: "pre" | "post" | "normal";
+}
 /**
  * Options for initializing or updating the context with new configuration values
  */
@@ -385,6 +390,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>;
+}
+type SelectHookResultItem<TContext extends PluginContext, TKey extends string> = InferHooksListItem<TContext, TKey> & {
+  context: TContext;
+};
+type SelectHookResult<TContext extends PluginContext, TKey extends string> = SelectHookResultItem<TContext, TKey>[];
+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 string>(key: TKey, options?: SelectHooksOptions) => SelectHookResult<PluginContext<TResolvedConfig>, TKey>;
+}
 interface PluginContext<out TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig>, UnpluginContext {
   /**
    * The environment specific resolved configuration
@@ -399,5 +510,6 @@ interface PluginContext<out TResolvedConfig extends ResolvedConfig = ResolvedCon
   logger: LogFn;
 }
 type BuildPluginContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> = UnpluginBuildContext & PluginContext<TResolvedConfig>;
+type WithUnpluginBuildContext<TContext extends PluginContext> = UnpluginBuildContext & TContext;
 //#endregion
-export { BuildPluginContext, Context, PluginContext, UnresolvedContext };
+export { APIContext, BuildPluginContext, Context, EnvironmentContext, PluginContext, SelectHooksOptions, UnresolvedContext, WithUnpluginBuildContext };

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

@@ -1,5 +1,7 @@
 import { ResolveOptions, VirtualFile, VirtualFileSystemInterface, WriteOptions } from "./fs.mjs";
 import { EnvironmentResolvedConfig, ResolvedConfig, ResolvedEntryTypeDefinition } from "./resolved.mjs";
+import { HooksList, InferHooksListItem } from "./hooks.mjs";
+import { Plugin } from "./plugin.mjs";
 import { ParsedTypeScriptConfig } from "./tsconfig.mjs";
 import { InlineConfig, LogFn, UserConfig, WorkspaceConfig } from "./config.mjs";
 import { EnvPaths } from "@stryke/env/get-env-paths";
@@ -49,6 +51,9 @@ interface TransformResult$1 {
   code: string;
   map: SourceMap | null;
 }
+interface SelectHooksOptions {
+  order?: "pre" | "post" | "normal";
+}
 /**
  * Options for initializing or updating the context with new configuration values
  */
@@ -385,6 +390,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>;
+}
+type SelectHookResultItem<TContext extends PluginContext, TKey extends string> = InferHooksListItem<TContext, TKey> & {
+  context: TContext;
+};
+type SelectHookResult<TContext extends PluginContext, TKey extends string> = SelectHookResultItem<TContext, TKey>[];
+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 string>(key: TKey, options?: SelectHooksOptions) => SelectHookResult<PluginContext<TResolvedConfig>, TKey>;
+}
 interface PluginContext<out TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig>, UnpluginContext {
   /**
    * The environment specific resolved configuration
@@ -399,5 +510,6 @@ interface PluginContext<out TResolvedConfig extends ResolvedConfig = ResolvedCon
   logger: LogFn;
 }
 type BuildPluginContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> = UnpluginBuildContext & PluginContext<TResolvedConfig>;
+type WithUnpluginBuildContext<TContext extends PluginContext> = UnpluginBuildContext & TContext;
 //#endregion
-export { BuildPluginContext, Context, PluginContext, UnresolvedContext };
+export { APIContext, BuildPluginContext, Context, EnvironmentContext, PluginContext, SelectHooksOptions, UnresolvedContext, WithUnpluginBuildContext };

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

@@ -0,0 +1,32 @@
+import { UnpluginBuilderVariant } from "./build.cjs";
+import { Plugin, PluginHookFields, PluginHookFunctions } from "./plugin.cjs";
+import { PluginContext, WithUnpluginBuildContext } from "./context.cjs";
+import { UnpluginOptions } from "unplugin";
+
+//#region ../powerlines/src/types/hooks.d.ts
+type HookListOrders = "preOrdered" | "preEnforced" | "normal" | "postEnforced" | "postOrdered";
+type UnpluginHookFunctions<TContext extends PluginContext = PluginContext, TUnpluginBuilderVariant$1 extends UnpluginBuilderVariant = UnpluginBuilderVariant, TField$1 extends keyof Required<UnpluginOptions>[TUnpluginBuilderVariant$1] = keyof Required<UnpluginOptions>[TUnpluginBuilderVariant$1]> = Required<UnpluginOptions>[TUnpluginBuilderVariant$1][TField$1] extends infer THandler | {
+  handler: infer THandler;
+} ? THandler extends ((this: infer THandlerOriginalContext, ...args: infer THandlerArgs) => infer THandlerReturn) ? (this: THandlerOriginalContext & WithUnpluginBuildContext<TContext>, ...args: THandlerArgs) => THandlerReturn : THandler extends {
+  handler: infer THandlerFunction;
+} ? THandlerFunction extends ((this: infer THandlerFunctionOriginalContext, ...args: infer THandlerFunctionArgs) => infer THandlerFunctionReturn) ? (this: THandlerFunctionOriginalContext & WithUnpluginBuildContext<TContext>, ...args: THandlerFunctionArgs) => THandlerFunctionReturn : never : never : never;
+interface PluginHooksListItem<TContext extends PluginContext = PluginContext, TFields extends PluginHookFields<TContext> = PluginHookFields<TContext>> {
+  plugin: Plugin<TContext>;
+  handler: PluginHookFunctions<TContext>[TFields];
+}
+type PluginHooksList<TContext extends PluginContext = PluginContext, TFields extends PluginHookFields<TContext> = PluginHookFields<TContext>> = { [TKey in HookListOrders]?: PluginHooksListItem<TContext, TFields>[] | undefined };
+interface UnpluginHooksListItem<TContext extends PluginContext = PluginContext, TUnpluginBuilderVariant$1 extends UnpluginBuilderVariant = UnpluginBuilderVariant, TField$1 extends keyof Required<UnpluginOptions>[TUnpluginBuilderVariant$1] = keyof Required<UnpluginOptions>[TUnpluginBuilderVariant$1]> {
+  plugin: Plugin<TContext>;
+  handler: UnpluginHookFunctions<TContext, TUnpluginBuilderVariant$1, TField$1>;
+}
+type UnpluginHookList<TContext extends PluginContext = PluginContext, TUnpluginBuilderVariant$1 extends UnpluginBuilderVariant = UnpluginBuilderVariant, TField$1 extends keyof UnpluginOptions[TUnpluginBuilderVariant$1] = keyof UnpluginOptions[TUnpluginBuilderVariant$1]> = { [TKey in HookListOrders]?: UnpluginHooksListItem<TContext, TUnpluginBuilderVariant$1, TField$1>[] | undefined };
+type UnpluginHookVariantField<TContext extends PluginContext = PluginContext, TUnpluginBuilderVariant$1 extends UnpluginBuilderVariant = UnpluginBuilderVariant> = { [TKey in keyof UnpluginOptions[TUnpluginBuilderVariant$1]]?: UnpluginHookList<TContext, TUnpluginBuilderVariant$1, TKey> };
+type UnpluginHookVariant<TContext extends PluginContext = PluginContext> = { [TKey in UnpluginBuilderVariant]?: UnpluginHookVariantField<TContext, TKey> };
+type HookFields<TContext extends PluginContext = PluginContext> = PluginHookFields<TContext> | UnpluginBuilderVariant;
+type HooksList<TContext extends PluginContext = PluginContext> = { [TField in HookFields<TContext>]?: TField extends PluginHookFields<TContext> ? PluginHooksList<TContext, TField> : TField extends UnpluginBuilderVariant ? UnpluginHookVariant<TContext>[TField] : never };
+type InferHooksListItem<TContext extends PluginContext, TKey$1 extends string> = TKey$1 extends `${infer TUnpluginBuilderVariant}:${infer TUnpluginField}` ? TUnpluginBuilderVariant extends UnpluginBuilderVariant ? TUnpluginField extends keyof Required<UnpluginOptions>[TUnpluginBuilderVariant] ? UnpluginHooksListItem<TContext, TUnpluginBuilderVariant, TUnpluginField> : never : never : TKey$1 extends keyof PluginHookFunctions<TContext> ? PluginHooksListItem<TContext, TKey$1> : never;
+type InferHookFunction<TContext extends PluginContext, TKey$1 extends string> = TKey$1 extends `${infer TUnpluginBuilderVariant}:${infer TUnpluginField}` ? TUnpluginBuilderVariant extends UnpluginBuilderVariant ? TUnpluginField extends keyof Required<UnpluginOptions>[TUnpluginBuilderVariant] ? UnpluginHookFunctions<TContext, TUnpluginBuilderVariant, TUnpluginField> : never : never : TKey$1 extends keyof PluginHookFunctions<TContext> ? PluginHookFunctions<TContext>[TKey$1] : never;
+type InferHookReturnType<TContext extends PluginContext, TKey$1 extends string> = ReturnType<InferHookFunction<TContext, TKey$1>>;
+type InferHookParameters<TContext extends PluginContext, TKey$1 extends string> = Parameters<InferHookFunction<TContext, TKey$1>>;
+//#endregion
+export { HooksList, InferHookParameters, InferHookReturnType, InferHooksListItem };

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

@@ -0,0 +1,32 @@
+import { UnpluginBuilderVariant } from "./build.mjs";
+import { Plugin, PluginHookFields, PluginHookFunctions } from "./plugin.mjs";
+import { PluginContext, WithUnpluginBuildContext } from "./context.mjs";
+import { UnpluginOptions } from "unplugin";
+
+//#region ../powerlines/src/types/hooks.d.ts
+type HookListOrders = "preOrdered" | "preEnforced" | "normal" | "postEnforced" | "postOrdered";
+type UnpluginHookFunctions<TContext extends PluginContext = PluginContext, TUnpluginBuilderVariant$1 extends UnpluginBuilderVariant = UnpluginBuilderVariant, TField$1 extends keyof Required<UnpluginOptions>[TUnpluginBuilderVariant$1] = keyof Required<UnpluginOptions>[TUnpluginBuilderVariant$1]> = Required<UnpluginOptions>[TUnpluginBuilderVariant$1][TField$1] extends infer THandler | {
+  handler: infer THandler;
+} ? THandler extends ((this: infer THandlerOriginalContext, ...args: infer THandlerArgs) => infer THandlerReturn) ? (this: THandlerOriginalContext & WithUnpluginBuildContext<TContext>, ...args: THandlerArgs) => THandlerReturn : THandler extends {
+  handler: infer THandlerFunction;
+} ? THandlerFunction extends ((this: infer THandlerFunctionOriginalContext, ...args: infer THandlerFunctionArgs) => infer THandlerFunctionReturn) ? (this: THandlerFunctionOriginalContext & WithUnpluginBuildContext<TContext>, ...args: THandlerFunctionArgs) => THandlerFunctionReturn : never : never : never;
+interface PluginHooksListItem<TContext extends PluginContext = PluginContext, TFields extends PluginHookFields<TContext> = PluginHookFields<TContext>> {
+  plugin: Plugin<TContext>;
+  handler: PluginHookFunctions<TContext>[TFields];
+}
+type PluginHooksList<TContext extends PluginContext = PluginContext, TFields extends PluginHookFields<TContext> = PluginHookFields<TContext>> = { [TKey in HookListOrders]?: PluginHooksListItem<TContext, TFields>[] | undefined };
+interface UnpluginHooksListItem<TContext extends PluginContext = PluginContext, TUnpluginBuilderVariant$1 extends UnpluginBuilderVariant = UnpluginBuilderVariant, TField$1 extends keyof Required<UnpluginOptions>[TUnpluginBuilderVariant$1] = keyof Required<UnpluginOptions>[TUnpluginBuilderVariant$1]> {
+  plugin: Plugin<TContext>;
+  handler: UnpluginHookFunctions<TContext, TUnpluginBuilderVariant$1, TField$1>;
+}
+type UnpluginHookList<TContext extends PluginContext = PluginContext, TUnpluginBuilderVariant$1 extends UnpluginBuilderVariant = UnpluginBuilderVariant, TField$1 extends keyof UnpluginOptions[TUnpluginBuilderVariant$1] = keyof UnpluginOptions[TUnpluginBuilderVariant$1]> = { [TKey in HookListOrders]?: UnpluginHooksListItem<TContext, TUnpluginBuilderVariant$1, TField$1>[] | undefined };
+type UnpluginHookVariantField<TContext extends PluginContext = PluginContext, TUnpluginBuilderVariant$1 extends UnpluginBuilderVariant = UnpluginBuilderVariant> = { [TKey in keyof UnpluginOptions[TUnpluginBuilderVariant$1]]?: UnpluginHookList<TContext, TUnpluginBuilderVariant$1, TKey> };
+type UnpluginHookVariant<TContext extends PluginContext = PluginContext> = { [TKey in UnpluginBuilderVariant]?: UnpluginHookVariantField<TContext, TKey> };
+type HookFields<TContext extends PluginContext = PluginContext> = PluginHookFields<TContext> | UnpluginBuilderVariant;
+type HooksList<TContext extends PluginContext = PluginContext> = { [TField in HookFields<TContext>]?: TField extends PluginHookFields<TContext> ? PluginHooksList<TContext, TField> : TField extends UnpluginBuilderVariant ? UnpluginHookVariant<TContext>[TField] : never };
+type InferHooksListItem<TContext extends PluginContext, TKey$1 extends string> = TKey$1 extends `${infer TUnpluginBuilderVariant}:${infer TUnpluginField}` ? TUnpluginBuilderVariant extends UnpluginBuilderVariant ? TUnpluginField extends keyof Required<UnpluginOptions>[TUnpluginBuilderVariant] ? UnpluginHooksListItem<TContext, TUnpluginBuilderVariant, TUnpluginField> : never : never : TKey$1 extends keyof PluginHookFunctions<TContext> ? PluginHooksListItem<TContext, TKey$1> : never;
+type InferHookFunction<TContext extends PluginContext, TKey$1 extends string> = TKey$1 extends `${infer TUnpluginBuilderVariant}:${infer TUnpluginField}` ? TUnpluginBuilderVariant extends UnpluginBuilderVariant ? TUnpluginField extends keyof Required<UnpluginOptions>[TUnpluginBuilderVariant] ? UnpluginHookFunctions<TContext, TUnpluginBuilderVariant, TUnpluginField> : never : never : TKey$1 extends keyof PluginHookFunctions<TContext> ? PluginHookFunctions<TContext>[TKey$1] : never;
+type InferHookReturnType<TContext extends PluginContext, TKey$1 extends string> = ReturnType<InferHookFunction<TContext, TKey$1>>;
+type InferHookParameters<TContext extends PluginContext, TKey$1 extends string> = Parameters<InferHookFunction<TContext, TKey$1>>;
+//#endregion
+export { HooksList, InferHookParameters, InferHookReturnType, InferHooksListItem };