powerlines 0.19.5 → 0.20.0

package/dist/plugin-utils/{config-48EWGWXq.d.cts → config-pwKiZvzJ.d.cts}

@@ -1,7 +1,7 @@
 import { Format } from '@storm-software/build-tools/types';
 import { LogLevelLabel } from '@storm-software/config-tools/types';
 import { StormWorkspaceConfig } from '@storm-software/config/types';
-import { NonUndefined, MaybePromise, FunctionLike, DeepPartial } from '@stryke/types/base';
+import { NonUndefined, MaybePromise, FunctionLike, DeepPartial as DeepPartial$1 } from '@stryke/types/base';
 import { TypeDefinition, TypeDefinitionParameter } from '@stryke/types/configuration';
 import { AssetGlob } from '@stryke/types/file';
 import { ResolvedPreviewOptions, PreviewOptions } from 'vite';
@@ -28,6 +28,73 @@ interface BuildConfig {
      * @defaultValue "neutral"
      */
     platform?: "node" | "browser" | "neutral";
+    /**
+     * Array of strings indicating the order in which fields in a package.json file should be resolved to determine the entry point for a module.
+     *
+     * @defaultValue `['browser', 'module', 'jsnext:main', 'jsnext']`
+     */
+    mainFields?: string[];
+    /**
+     * Array of strings indicating what conditions should be used for module resolution.
+     */
+    conditions?: string[];
+    /**
+     * Array of strings indicating what file extensions should be used for module resolution.
+     *
+     * @defaultValue `['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json']`
+     */
+    extensions?: string[];
+    /**
+     * Array of strings indicating what modules should be deduplicated to a single version in the build.
+     *
+     * @remarks
+     * This option is useful for ensuring that only one version of a module is included in the bundle, which can help reduce bundle size and avoid conflicts.
+     */
+    dedupe?: string[];
+    /**
+     * Array of strings or regular expressions that indicate what modules are builtin for the environment.
+     */
+    builtins?: (string | RegExp)[];
+    /**
+     * Define global variable replacements.
+     *
+     * @remarks
+     * This option allows you to specify global constants that will be replaced in the code during the build process. It is similar to the `define` option in esbuild and Vite, enabling you to replace specific identifiers with constant expressions at build time.
+     *
+     * @example
+     * ```ts
+     * {
+     *   define: {
+     *     __VERSION__: '"1.0.0"',
+     *     __DEV__: 'process.env.NODE_ENV !== "production"'
+     *   }
+     * }
+     * ```
+     *
+     * @see https://esbuild.github.io/api/#define
+     * @see https://vitejs.dev/config/build-options.html#define
+     * @see https://github.com/rollup/plugins/tree/master/packages/replace
+     */
+    define?: Record<string, any>;
+    /**
+     * Global variables that will have import statements injected where necessary
+     *
+     * @remarks
+     * This option allows you to specify global variables that should be automatically imported from specified modules whenever they are used in the code. This is particularly useful for polyfilling Node.js globals in a browser environment.
+     *
+     * @example
+     * ```ts
+     * {
+     *   inject: {
+     *     process: 'process/browser',
+     *     Buffer: ['buffer', 'Buffer'],
+     *   }
+     * }
+     * ```
+     *
+     * @see https://github.com/rollup/plugins/tree/master/packages/inject
+     */
+    inject?: Record<string, string | string[]>;
     /**
      * The alias mappings to use for module resolution during the build process.
      *
@@ -43,6 +110,8 @@ interface BuildConfig {
      *   }
      * }
      * ```
+     *
+     * @see https://github.com/rollup/plugins/tree/master/packages/alias
      */
     alias?: Record<string, string>;
     /**
@@ -61,13 +130,14 @@ interface BuildConfig {
      */
     skipNodeModulesBundle?: boolean;
     /**
-     * Should the Powerlines processes skip the `"prepare"` task prior to building?
+     * An optional set of override options to apply to the selected build variant.
      *
-     * @defaultValue false
+     * @remarks
+     * This option allows you to provide configuration options with the guarantee that they will **not** be overridden and will take precedence over other build configurations.
      */
-    skipPrepare?: boolean;
+    override?: Record<string, any>;
 }
-type BuildResolvedConfig = BuildConfig;
+type BuildResolvedConfig = Omit<BuildConfig, "override">;
 
 declare const SUPPORTED_COMMANDS: readonly ["new", "clean", "prepare", "lint", "test", "build", "docs", "release", "finalize"];
 type CommandType = ArrayValues<typeof SUPPORTED_COMMANDS>;
@@ -82,7 +152,7 @@ interface ResolvedEntryTypeDefinition extends TypeDefinition {
      */
     output?: string;
 }
-type EnvironmentResolvedConfig = Omit<EnvironmentConfig, "consumer" | "mode" | "ssr" | "preview" | "mainFields" | "extensions"> & Required<Pick<EnvironmentConfig, "consumer" | "mode" | "ssr" | "mainFields" | "extensions">> & {
+type EnvironmentResolvedConfig = Omit<EnvironmentConfig, "consumer" | "mode" | "ssr" | "preview"> & Required<Pick<EnvironmentConfig, "consumer" | "mode" | "ssr">> & {
     /**
      * The name of the environment
      */
@@ -99,7 +169,7 @@ type OutputResolvedConfig = Required<Omit<OutputConfig, "assets"> & {
 /**
  * The resolved options for the Powerlines project configuration.
  */
-type ResolvedConfig<TUserConfig extends UserConfig = UserConfig> = Omit<TUserConfig, "name" | "title" | "plugins" | "mode" | "environments" | "platform" | "tsconfig" | "lint" | "test" | "build" | "transform" | "override" | "root" | "variant" | "type" | "output" | "logLevel" | "framework"> & Required<Pick<TUserConfig, "name" | "title" | "plugins" | "mode" | "environments" | "tsconfig" | "lint" | "test" | "build" | "transform" | "override" | "framework">> & {
+type ResolvedConfig<TUserConfig extends UserConfig = UserConfig> = Omit<TUserConfig, "name" | "title" | "plugins" | "mode" | "environments" | "platform" | "tsconfig" | "lint" | "test" | "build" | "transform" | "variant" | "type" | "output" | "logLevel" | "framework"> & Required<Pick<TUserConfig, "name" | "title" | "plugins" | "mode" | "environments" | "tsconfig" | "lint" | "test" | "build" | "transform" | "framework">> & {
     /**
      * The configuration options that were provided inline to the Powerlines CLI.
      */
@@ -130,6 +200,13 @@ type ResolvedConfig<TUserConfig extends UserConfig = UserConfig> = Omit<TUserCon
      * The output configuration options to use for the build process
      */
     output: OutputResolvedConfig;
+    /**
+     * Configuration provided to build processes
+     *
+     * @remarks
+     * This configuration can be used by plugins during the `build` command. It will generally contain options specific to the selected {@link BuildVariant | build variant}.
+     */
+    build: Omit<TUserConfig["build"], "override"> & Required<Pick<Required<TUserConfig["build"]>, "override">>;
     /**
      * The log level to use for the Powerlines processes.
      *
@@ -160,6 +237,10 @@ interface GenerateTypesResult {
     directives?: string[];
     code: string;
 }
+type DeepPartial<T> = {
+    [K in keyof T]?: DeepPartial<T[K]>;
+};
+type ConfigResult<TContext extends PluginContext = PluginContext> = DeepPartial<TContext["config"]> & Record<string, any>;
 interface BasePluginHookFunctions<TContext extends PluginContext = PluginContext> extends Record<CommandType, (this: TContext) => MaybePromise<void>> {
     /**
      * A function that returns configuration options to be merged with the build context's options.
@@ -175,7 +256,7 @@ interface BasePluginHookFunctions<TContext extends PluginContext = PluginContext
      * @param config - The partial configuration object to be modified.
      * @returns A promise that resolves to a partial configuration object.
      */
-    config: (this: Context<TContext["config"]>) => MaybePromise<Partial<TContext["config"]["userConfig"]>>;
+    config: (this: UnresolvedContext<TContext["config"]>) => MaybePromise<ConfigResult<TContext>>;
     /**
      * Modify environment configs before it's resolved. The hook can either mutate the passed-in environment config directly, or return a partial config object that will be deeply merged into existing config.
      *
@@ -283,7 +364,7 @@ type PluginHooks<TContext extends PluginContext = PluginContext> = {
      * @param config - The partial configuration object to be modified.
      * @returns A promise that resolves to a partial configuration object.
      */
-    config: PluginHook<(this: Context<TContext["config"]>) => MaybePromise<Partial<TContext["config"]["userConfig"]>>> | Partial<TContext["config"]["userConfig"]>;
+    config: PluginHook<(this: UnresolvedContext<TContext["config"]>) => MaybePromise<ConfigResult<TContext>>> | ConfigResult<TContext>;
     /**
      * A hook that is called to transform the source code.
      *
@@ -858,7 +939,13 @@ interface InitContextOptions {
      */
     isHighPriority: boolean;
 }
-interface Context<TResolvedConfig extends ResolvedConfig = ResolvedConfig> {
+/**
+ * The unresolved Powerlines context.
+ *
+ * @remarks
+ * This context is used before the user configuration has been fully resolved after the `config`.
+ */
+interface UnresolvedContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> {
     /**
      * The Storm workspace configuration
      */
@@ -866,7 +953,10 @@ interface Context<TResolvedConfig extends ResolvedConfig = ResolvedConfig> {
     /**
      * An object containing the options provided to Powerlines
      */
-    config: TResolvedConfig;
+    config: Omit<TResolvedConfig["userConfig"], "build" | "output"> & Required<Pick<TResolvedConfig["userConfig"], "build" | "output">> & {
+        projectRoot: NonUndefined<TResolvedConfig["userConfig"]["root"]>;
+        output: TResolvedConfig["output"];
+    };
     /**
      * A logging function for the Powerlines engine
      */
@@ -1023,6 +1113,12 @@ interface Context<TResolvedConfig extends ResolvedConfig = ResolvedConfig> {
      */
     extendLog: (name: string) => LogFn;
 }
+type Context<TResolvedConfig extends ResolvedConfig = ResolvedConfig> = Omit<UnresolvedContext<TResolvedConfig>, "config"> & {
+    /**
+     * The fully resolved Powerlines configuration
+     */
+    config: TResolvedConfig;
+};
 interface PluginContext<out TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig>, UnpluginContext {
     /**
      * The environment specific resolved configuration
@@ -1062,7 +1158,7 @@ type PluginConfigObject<TContext extends PluginContext = PluginContext, TOptions
  * A configuration tuple for a Powerlines plugin.
  */
 type PluginConfig<TContext extends PluginContext = PluginContext> = string | PluginFactory<TContext, void> | Plugin<TContext> | Promise<Plugin<TContext>> | PluginConfigTuple<TContext> | PluginConfigObject<TContext>;
-type PartialPlugin<in out TContext extends PluginContext = PluginContext> = DeepPartial<Plugin<TContext>>;
+type PartialPlugin<in out TContext extends PluginContext = PluginContext> = DeepPartial$1<Plugin<TContext>>;
 type PartialPluginFactory<in out TContext extends PluginContext = PluginContext, TOptions = any> = (options: TOptions) => MaybePromise<PartialPlugin<TContext>>;
 type ProjectType = "application" | "library";
 interface OutputConfig {
@@ -1163,24 +1259,33 @@ interface BaseConfig {
      * The entry point(s) for the application
      */
     entry?: TypeDefinitionParameter | TypeDefinitionParameter[];
+    /**
+     * Configuration for the output of the build process
+     */
+    output?: OutputConfig;
     /**
      * Configuration for linting the source code
+     *
+     * @remarks
+     * If set to `false`, linting will be disabled.
      */
     lint?: Record<string, any> | false;
     /**
      * Configuration for testing the source code
+     *
+     * @remarks
+     * If set to `false`, testing will be disabled.
      */
     test?: Record<string, any> | false;
-    /**
-     * Configuration for the output of the build process
-     */
-    output?: OutputConfig;
     /**
      * Configuration for the transformation of the source code
      */
     transform?: Record<string, any>;
     /**
-     * Options to to provide to the build process
+     * Configuration provided to build processes
+     *
+     * @remarks
+     * This configuration can be used by plugins during the `build` command. It will generally contain options specific to the selected {@link BuildVariant | build variant}.
      */
     build?: BuildConfig;
     /**
@@ -1210,37 +1315,6 @@ interface BaseConfig {
     tsconfigRaw?: TSConfig;
 }
 interface EnvironmentConfig extends BaseConfig {
-    /**
-     * Array of strings indicating the order in which fields in a package.json file should be resolved to determine the entry point for a module.
-     *
-     * @defaultValue `['browser', 'module', 'jsnext:main', 'jsnext']`
-     */
-    mainFields?: string[];
-    /**
-     * Array of strings indicating what conditions should be used for module resolution.
-     */
-    conditions?: string[];
-    /**
-     * Array of strings indicating what conditions should be used for external modules.
-     */
-    externalConditions?: string[];
-    /**
-     * Array of strings indicating what file extensions should be used for module resolution.
-     *
-     * @defaultValue `['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json']`
-     */
-    extensions?: string[];
-    /**
-     * Array of strings indicating what modules should be deduplicated to a single version in the build.
-     *
-     * @remarks
-     * This option is useful for ensuring that only one version of a module is included in the bundle, which can help reduce bundle size and avoid conflicts.
-     */
-    dedupe?: string[];
-    /**
-     * Array of strings or regular expressions that indicate what modules are builtin for the environment.
-     */
-    builtins?: (string | RegExp)[];
     /**
      * Configuration options for the preview server
      */
@@ -1313,14 +1387,26 @@ interface CommonUserConfig extends BaseConfig {
      */
     framework?: string;
 }
-type UserConfig<TBuildConfig extends BuildConfig = BuildConfig, TBuildResolvedConfig extends BuildResolvedConfig = BuildResolvedConfig, TBuildVariant extends string = any> = CommonUserConfig & {
-    build?: TBuildConfig & {
+type UserConfig<TBuildConfig extends BuildConfig = BuildConfig, TBuildResolvedConfig extends BuildResolvedConfig = BuildResolvedConfig, TBuildVariant extends string = any> = Omit<CommonUserConfig, "build"> & {
+    /**
+     * Configuration provided to build processes
+     *
+     * @remarks
+     * This configuration can be used by plugins during the `build` command. It will generally contain options specific to the selected {@link BuildVariant | build variant}.
+     */
+    build: Omit<TBuildConfig, "override"> & {
         /**
          * The build variant being used by the Powerlines engine.
          */
         variant?: TBuildVariant;
+        /**
+         * An optional set of override options to apply to the selected build variant.
+         *
+         * @remarks
+         * This option allows you to provide configuration options with the guarantee that they will **not** be overridden and will take precedence over other build configurations.
+         */
+        override?: Partial<TBuildResolvedConfig>;
     };
-    override?: Partial<TBuildResolvedConfig>;
 };
 type PowerlinesCommand = "new" | "prepare" | "build" | "lint" | "test" | "docs" | "release" | "clean";
 /**
@@ -1333,4 +1419,4 @@ type InlineConfig<TUserConfig extends UserConfig = UserConfig> = Partial<TUserCo
     command: PowerlinesCommand;
 };
 
-export type { BuildVariant as B, Context as C, ExternalPluginHookFunctions as E, GenerateTypesResult as G, PluginContext as P, ResolvedConfig as R, Plugin as a, PluginFactory as b, PartialPlugin as c, PartialPluginFactory as d, BasePluginHookFunctions as e, PluginHookFunctions as f, PluginHookObject as g, PluginConfigObject as h, PluginConfigTuple as i, PluginConfig as j, PluginHook as k, EnvironmentConfig as l, EnvironmentResolvedConfig as m };
+export type { BuildVariant as B, Context as C, ExternalPluginHookFunctions as E, GenerateTypesResult as G, PluginContext as P, ResolvedConfig as R, UnresolvedContext as U, Plugin as a, PluginFactory as b, PartialPlugin as c, PartialPluginFactory as d, BasePluginHookFunctions as e, PluginHookFunctions as f, PluginHookObject as g, PluginConfigObject as h, PluginConfigTuple as i, PluginConfig as j, PluginHook as k, ConfigResult as l, EnvironmentConfig as m, EnvironmentResolvedConfig as n };

package/dist/plugin-utils/{config-48EWGWXq.d.ts → config-pwKiZvzJ.d.ts}

@@ -1,7 +1,7 @@
 import { Format } from '@storm-software/build-tools/types';
 import { LogLevelLabel } from '@storm-software/config-tools/types';
 import { StormWorkspaceConfig } from '@storm-software/config/types';
-import { NonUndefined, MaybePromise, FunctionLike, DeepPartial } from '@stryke/types/base';
+import { NonUndefined, MaybePromise, FunctionLike, DeepPartial as DeepPartial$1 } from '@stryke/types/base';
 import { TypeDefinition, TypeDefinitionParameter } from '@stryke/types/configuration';
 import { AssetGlob } from '@stryke/types/file';
 import { ResolvedPreviewOptions, PreviewOptions } from 'vite';
@@ -28,6 +28,73 @@ interface BuildConfig {
      * @defaultValue "neutral"
      */
     platform?: "node" | "browser" | "neutral";
+    /**
+     * Array of strings indicating the order in which fields in a package.json file should be resolved to determine the entry point for a module.
+     *
+     * @defaultValue `['browser', 'module', 'jsnext:main', 'jsnext']`
+     */
+    mainFields?: string[];
+    /**
+     * Array of strings indicating what conditions should be used for module resolution.
+     */
+    conditions?: string[];
+    /**
+     * Array of strings indicating what file extensions should be used for module resolution.
+     *
+     * @defaultValue `['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json']`
+     */
+    extensions?: string[];
+    /**
+     * Array of strings indicating what modules should be deduplicated to a single version in the build.
+     *
+     * @remarks
+     * This option is useful for ensuring that only one version of a module is included in the bundle, which can help reduce bundle size and avoid conflicts.
+     */
+    dedupe?: string[];
+    /**
+     * Array of strings or regular expressions that indicate what modules are builtin for the environment.
+     */
+    builtins?: (string | RegExp)[];
+    /**
+     * Define global variable replacements.
+     *
+     * @remarks
+     * This option allows you to specify global constants that will be replaced in the code during the build process. It is similar to the `define` option in esbuild and Vite, enabling you to replace specific identifiers with constant expressions at build time.
+     *
+     * @example
+     * ```ts
+     * {
+     *   define: {
+     *     __VERSION__: '"1.0.0"',
+     *     __DEV__: 'process.env.NODE_ENV !== "production"'
+     *   }
+     * }
+     * ```
+     *
+     * @see https://esbuild.github.io/api/#define
+     * @see https://vitejs.dev/config/build-options.html#define
+     * @see https://github.com/rollup/plugins/tree/master/packages/replace
+     */
+    define?: Record<string, any>;
+    /**
+     * Global variables that will have import statements injected where necessary
+     *
+     * @remarks
+     * This option allows you to specify global variables that should be automatically imported from specified modules whenever they are used in the code. This is particularly useful for polyfilling Node.js globals in a browser environment.
+     *
+     * @example
+     * ```ts
+     * {
+     *   inject: {
+     *     process: 'process/browser',
+     *     Buffer: ['buffer', 'Buffer'],
+     *   }
+     * }
+     * ```
+     *
+     * @see https://github.com/rollup/plugins/tree/master/packages/inject
+     */
+    inject?: Record<string, string | string[]>;
     /**
      * The alias mappings to use for module resolution during the build process.
      *
@@ -43,6 +110,8 @@ interface BuildConfig {
      *   }
      * }
      * ```
+     *
+     * @see https://github.com/rollup/plugins/tree/master/packages/alias
      */
     alias?: Record<string, string>;
     /**
@@ -61,13 +130,14 @@ interface BuildConfig {
      */
     skipNodeModulesBundle?: boolean;
     /**
-     * Should the Powerlines processes skip the `"prepare"` task prior to building?
+     * An optional set of override options to apply to the selected build variant.
      *
-     * @defaultValue false
+     * @remarks
+     * This option allows you to provide configuration options with the guarantee that they will **not** be overridden and will take precedence over other build configurations.
      */
-    skipPrepare?: boolean;
+    override?: Record<string, any>;
 }
-type BuildResolvedConfig = BuildConfig;
+type BuildResolvedConfig = Omit<BuildConfig, "override">;
 
 declare const SUPPORTED_COMMANDS: readonly ["new", "clean", "prepare", "lint", "test", "build", "docs", "release", "finalize"];
 type CommandType = ArrayValues<typeof SUPPORTED_COMMANDS>;
@@ -82,7 +152,7 @@ interface ResolvedEntryTypeDefinition extends TypeDefinition {
      */
     output?: string;
 }
-type EnvironmentResolvedConfig = Omit<EnvironmentConfig, "consumer" | "mode" | "ssr" | "preview" | "mainFields" | "extensions"> & Required<Pick<EnvironmentConfig, "consumer" | "mode" | "ssr" | "mainFields" | "extensions">> & {
+type EnvironmentResolvedConfig = Omit<EnvironmentConfig, "consumer" | "mode" | "ssr" | "preview"> & Required<Pick<EnvironmentConfig, "consumer" | "mode" | "ssr">> & {
     /**
      * The name of the environment
      */
@@ -99,7 +169,7 @@ type OutputResolvedConfig = Required<Omit<OutputConfig, "assets"> & {
 /**
  * The resolved options for the Powerlines project configuration.
  */
-type ResolvedConfig<TUserConfig extends UserConfig = UserConfig> = Omit<TUserConfig, "name" | "title" | "plugins" | "mode" | "environments" | "platform" | "tsconfig" | "lint" | "test" | "build" | "transform" | "override" | "root" | "variant" | "type" | "output" | "logLevel" | "framework"> & Required<Pick<TUserConfig, "name" | "title" | "plugins" | "mode" | "environments" | "tsconfig" | "lint" | "test" | "build" | "transform" | "override" | "framework">> & {
+type ResolvedConfig<TUserConfig extends UserConfig = UserConfig> = Omit<TUserConfig, "name" | "title" | "plugins" | "mode" | "environments" | "platform" | "tsconfig" | "lint" | "test" | "build" | "transform" | "variant" | "type" | "output" | "logLevel" | "framework"> & Required<Pick<TUserConfig, "name" | "title" | "plugins" | "mode" | "environments" | "tsconfig" | "lint" | "test" | "build" | "transform" | "framework">> & {
     /**
      * The configuration options that were provided inline to the Powerlines CLI.
      */
@@ -130,6 +200,13 @@ type ResolvedConfig<TUserConfig extends UserConfig = UserConfig> = Omit<TUserCon
      * The output configuration options to use for the build process
      */
     output: OutputResolvedConfig;
+    /**
+     * Configuration provided to build processes
+     *
+     * @remarks
+     * This configuration can be used by plugins during the `build` command. It will generally contain options specific to the selected {@link BuildVariant | build variant}.
+     */
+    build: Omit<TUserConfig["build"], "override"> & Required<Pick<Required<TUserConfig["build"]>, "override">>;
     /**
      * The log level to use for the Powerlines processes.
      *
@@ -160,6 +237,10 @@ interface GenerateTypesResult {
     directives?: string[];
     code: string;
 }
+type DeepPartial<T> = {
+    [K in keyof T]?: DeepPartial<T[K]>;
+};
+type ConfigResult<TContext extends PluginContext = PluginContext> = DeepPartial<TContext["config"]> & Record<string, any>;
 interface BasePluginHookFunctions<TContext extends PluginContext = PluginContext> extends Record<CommandType, (this: TContext) => MaybePromise<void>> {
     /**
      * A function that returns configuration options to be merged with the build context's options.
@@ -175,7 +256,7 @@ interface BasePluginHookFunctions<TContext extends PluginContext = PluginContext
      * @param config - The partial configuration object to be modified.
      * @returns A promise that resolves to a partial configuration object.
      */
-    config: (this: Context<TContext["config"]>) => MaybePromise<Partial<TContext["config"]["userConfig"]>>;
+    config: (this: UnresolvedContext<TContext["config"]>) => MaybePromise<ConfigResult<TContext>>;
     /**
      * Modify environment configs before it's resolved. The hook can either mutate the passed-in environment config directly, or return a partial config object that will be deeply merged into existing config.
      *
@@ -283,7 +364,7 @@ type PluginHooks<TContext extends PluginContext = PluginContext> = {
      * @param config - The partial configuration object to be modified.
      * @returns A promise that resolves to a partial configuration object.
      */
-    config: PluginHook<(this: Context<TContext["config"]>) => MaybePromise<Partial<TContext["config"]["userConfig"]>>> | Partial<TContext["config"]["userConfig"]>;
+    config: PluginHook<(this: UnresolvedContext<TContext["config"]>) => MaybePromise<ConfigResult<TContext>>> | ConfigResult<TContext>;
     /**
      * A hook that is called to transform the source code.
      *
@@ -858,7 +939,13 @@ interface InitContextOptions {
      */
     isHighPriority: boolean;
 }
-interface Context<TResolvedConfig extends ResolvedConfig = ResolvedConfig> {
+/**
+ * The unresolved Powerlines context.
+ *
+ * @remarks
+ * This context is used before the user configuration has been fully resolved after the `config`.
+ */
+interface UnresolvedContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> {
     /**
      * The Storm workspace configuration
      */
@@ -866,7 +953,10 @@ interface Context<TResolvedConfig extends ResolvedConfig = ResolvedConfig> {
     /**
      * An object containing the options provided to Powerlines
      */
-    config: TResolvedConfig;
+    config: Omit<TResolvedConfig["userConfig"], "build" | "output"> & Required<Pick<TResolvedConfig["userConfig"], "build" | "output">> & {
+        projectRoot: NonUndefined<TResolvedConfig["userConfig"]["root"]>;
+        output: TResolvedConfig["output"];
+    };
     /**
      * A logging function for the Powerlines engine
      */
@@ -1023,6 +1113,12 @@ interface Context<TResolvedConfig extends ResolvedConfig = ResolvedConfig> {
      */
     extendLog: (name: string) => LogFn;
 }
+type Context<TResolvedConfig extends ResolvedConfig = ResolvedConfig> = Omit<UnresolvedContext<TResolvedConfig>, "config"> & {
+    /**
+     * The fully resolved Powerlines configuration
+     */
+    config: TResolvedConfig;
+};
 interface PluginContext<out TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig>, UnpluginContext {
     /**
      * The environment specific resolved configuration
@@ -1062,7 +1158,7 @@ type PluginConfigObject<TContext extends PluginContext = PluginContext, TOptions
  * A configuration tuple for a Powerlines plugin.
  */
 type PluginConfig<TContext extends PluginContext = PluginContext> = string | PluginFactory<TContext, void> | Plugin<TContext> | Promise<Plugin<TContext>> | PluginConfigTuple<TContext> | PluginConfigObject<TContext>;
-type PartialPlugin<in out TContext extends PluginContext = PluginContext> = DeepPartial<Plugin<TContext>>;
+type PartialPlugin<in out TContext extends PluginContext = PluginContext> = DeepPartial$1<Plugin<TContext>>;
 type PartialPluginFactory<in out TContext extends PluginContext = PluginContext, TOptions = any> = (options: TOptions) => MaybePromise<PartialPlugin<TContext>>;
 type ProjectType = "application" | "library";
 interface OutputConfig {
@@ -1163,24 +1259,33 @@ interface BaseConfig {
      * The entry point(s) for the application
      */
     entry?: TypeDefinitionParameter | TypeDefinitionParameter[];
+    /**
+     * Configuration for the output of the build process
+     */
+    output?: OutputConfig;
     /**
      * Configuration for linting the source code
+     *
+     * @remarks
+     * If set to `false`, linting will be disabled.
      */
     lint?: Record<string, any> | false;
     /**
      * Configuration for testing the source code
+     *
+     * @remarks
+     * If set to `false`, testing will be disabled.
      */
     test?: Record<string, any> | false;
-    /**
-     * Configuration for the output of the build process
-     */
-    output?: OutputConfig;
     /**
      * Configuration for the transformation of the source code
      */
     transform?: Record<string, any>;
     /**
-     * Options to to provide to the build process
+     * Configuration provided to build processes
+     *
+     * @remarks
+     * This configuration can be used by plugins during the `build` command. It will generally contain options specific to the selected {@link BuildVariant | build variant}.
      */
     build?: BuildConfig;
     /**
@@ -1210,37 +1315,6 @@ interface BaseConfig {
     tsconfigRaw?: TSConfig;
 }
 interface EnvironmentConfig extends BaseConfig {
-    /**
-     * Array of strings indicating the order in which fields in a package.json file should be resolved to determine the entry point for a module.
-     *
-     * @defaultValue `['browser', 'module', 'jsnext:main', 'jsnext']`
-     */
-    mainFields?: string[];
-    /**
-     * Array of strings indicating what conditions should be used for module resolution.
-     */
-    conditions?: string[];
-    /**
-     * Array of strings indicating what conditions should be used for external modules.
-     */
-    externalConditions?: string[];
-    /**
-     * Array of strings indicating what file extensions should be used for module resolution.
-     *
-     * @defaultValue `['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json']`
-     */
-    extensions?: string[];
-    /**
-     * Array of strings indicating what modules should be deduplicated to a single version in the build.
-     *
-     * @remarks
-     * This option is useful for ensuring that only one version of a module is included in the bundle, which can help reduce bundle size and avoid conflicts.
-     */
-    dedupe?: string[];
-    /**
-     * Array of strings or regular expressions that indicate what modules are builtin for the environment.
-     */
-    builtins?: (string | RegExp)[];
     /**
      * Configuration options for the preview server
      */
@@ -1313,14 +1387,26 @@ interface CommonUserConfig extends BaseConfig {
      */
     framework?: string;
 }
-type UserConfig<TBuildConfig extends BuildConfig = BuildConfig, TBuildResolvedConfig extends BuildResolvedConfig = BuildResolvedConfig, TBuildVariant extends string = any> = CommonUserConfig & {
-    build?: TBuildConfig & {
+type UserConfig<TBuildConfig extends BuildConfig = BuildConfig, TBuildResolvedConfig extends BuildResolvedConfig = BuildResolvedConfig, TBuildVariant extends string = any> = Omit<CommonUserConfig, "build"> & {
+    /**
+     * Configuration provided to build processes
+     *
+     * @remarks
+     * This configuration can be used by plugins during the `build` command. It will generally contain options specific to the selected {@link BuildVariant | build variant}.
+     */
+    build: Omit<TBuildConfig, "override"> & {
         /**
          * The build variant being used by the Powerlines engine.
          */
         variant?: TBuildVariant;
+        /**
+         * An optional set of override options to apply to the selected build variant.
+         *
+         * @remarks
+         * This option allows you to provide configuration options with the guarantee that they will **not** be overridden and will take precedence over other build configurations.
+         */
+        override?: Partial<TBuildResolvedConfig>;
     };
-    override?: Partial<TBuildResolvedConfig>;
 };
 type PowerlinesCommand = "new" | "prepare" | "build" | "lint" | "test" | "docs" | "release" | "clean";
 /**
@@ -1333,4 +1419,4 @@ type InlineConfig<TUserConfig extends UserConfig = UserConfig> = Partial<TUserCo
     command: PowerlinesCommand;
 };
 
-export type { BuildVariant as B, Context as C, ExternalPluginHookFunctions as E, GenerateTypesResult as G, PluginContext as P, ResolvedConfig as R, Plugin as a, PluginFactory as b, PartialPlugin as c, PartialPluginFactory as d, BasePluginHookFunctions as e, PluginHookFunctions as f, PluginHookObject as g, PluginConfigObject as h, PluginConfigTuple as i, PluginConfig as j, PluginHook as k, EnvironmentConfig as l, EnvironmentResolvedConfig as m };
+export type { BuildVariant as B, Context as C, ExternalPluginHookFunctions as E, GenerateTypesResult as G, PluginContext as P, ResolvedConfig as R, UnresolvedContext as U, Plugin as a, PluginFactory as b, PartialPlugin as c, PartialPluginFactory as d, BasePluginHookFunctions as e, PluginHookFunctions as f, PluginHookObject as g, PluginConfigObject as h, PluginConfigTuple as i, PluginConfig as j, PluginHook as k, ConfigResult as l, EnvironmentConfig as m, EnvironmentResolvedConfig as n };

package/dist/plugin-utils/enforce.d.cts

@@ -1,4 +1,4 @@
-import { P as PluginContext, B as BuildVariant, a as Plugin, b as PluginFactory } from './config-48EWGWXq.cjs';
+import { P as PluginContext, B as BuildVariant, a as Plugin, b as PluginFactory } from './config-pwKiZvzJ.cjs';
 import '@storm-software/build-tools/types';
 import '@storm-software/config-tools/types';
 import '@storm-software/config/types';