@powerlines/core 0.45.3 → 0.46.1

package/dist/types/context.d.cts

@@ -1,9 +1,11 @@
-import { ResolveOptions, VirtualFile, VirtualFileSystemInterface, WriteOptions } from "./fs.cjs";
 import { Plugin } from "./plugin.cjs";
 import { HooksList, HooksListItem } from "./hooks.cjs";
+import { API } from "./api.cjs";
+import { ResolveOptions, VirtualFile, VirtualFileSystemInterface, WriteOptions } from "./fs.cjs";
 import { LogFn, LogLevelResolvedConfig, LogMessage, Logger, LoggerOptions } from "./logging.cjs";
 import { ParsedTypeScriptConfig } from "./tsconfig.cjs";
-import { EngineOptions, EnvironmentResolvedConfig, ExecutionOptions, InitialConfig, ParsedUserConfig, ResolvedConfig, ResolvedEntryTypeDefinition } from "./config.cjs";
+import { EngineOptions, EnvironmentResolvedConfig, ExecutionOptions, ParsedUserConfig, ResolvedConfig, ResolvedEntryTypeDefinition, UserConfig } from "./config.cjs";
+import { DeepPartial, DeepReadonly, RequiredKeys } from "@stryke/types/base";
 import { Jiti } from "jiti";
 import { EnvPaths } from "@stryke/env/get-env-paths";
 import { FetchRequestOptions } from "@stryke/http/fetch";
@@ -136,10 +138,6 @@ interface ResolveResult extends ExternalIdResult {
  * This context provides the foundational structure for interacting with the Powerlines engine.
  */
 interface BaseContext {
-  /**
-   * The options provided to the Powerlines process
-   */
-  options: EngineOptions;
   /**
    * The timestamp when the context was initialized
    */
@@ -157,9 +155,9 @@ interface BaseContext {
    */
   configFile: ParsedUserConfig;
   /**
-   * The initial configuration provided when initializing the context, which may be used during the setup process to ensure that the configuration is properly merged and applied to the context. This is typically the user configuration provided in the Powerlines configuration file, but may also include additional configuration options provided by plugins or other sources.
+   * The options provided to the Powerlines process, resolved with default values and merged with any configuration provided by plugins or other sources. This is typically the final configuration used during the build process, but may also include additional options that are relevant to the context and its interactions with the Powerlines engine.
    */
-  initialConfig: InitialConfig<any>;
+  options: RequiredKeys<EngineOptions, "mode" | "cwd" | "root" | "framework">;
   /**
    * The log level to use for the Powerlines processes.
    */
@@ -220,13 +218,6 @@ interface BaseContext {
    * @returns A logger client instance that extends the current logger with the provided configuration options.
    */
   extendLogger: (options: LoggerOptions, logFn?: LogFn) => Logger;
-  /**
-   * A function to create a deep clone of the context
-   *
-   * @remarks
-   * This function is used to create a copy of the context for a specific environment, allowing for environment-specific modifications without affecting the global context.
-   */
-  clone: () => Promise<BaseContext>;
 }
 interface ExecutionStateItem {
   /**
@@ -278,6 +269,23 @@ interface ExecutionState {
  * This context is used during the execution of the Powerlines engine, providing access to the input user configurations.
  */
 interface EngineContext extends BaseContext {
+  /**
+   * The initial options provided to the Powerlines process before any resolution or merging. This is typically the user configuration provided in the Powerlines configuration file, but may also include additional configuration options provided by plugins or other sources.
+   */
+  readonly initialOptions: EngineOptions;
+  /**
+   * The options provided to the Powerlines process
+   */
+  options: RequiredKeys<Omit<EngineOptions, "logLevel">, "name" | "root" | "cwd" | "mode" | "framework"> & {
+    /**
+     * The log level to use for logging messages during the build process. This can be a string indicating the log level or a more detailed configuration object that allows for specifying different log levels for different categories of logs.
+     */
+    logLevel: LogLevelResolvedConfig;
+  };
+  /**
+   * The initial user configuration provided to the Powerlines process before any resolution or merging. This is typically the user configuration provided in the Powerlines configuration file, but may also include additional configuration options provided by plugins or other sources.
+   */
+  readonly initialConfig: DeepPartial<UserConfig>;
   /**
    * A list of all command executions that will be run during the lifecycle of the engine
    */
@@ -291,22 +299,25 @@ interface EngineContext extends BaseContext {
  */
 interface UnresolvedContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends BaseContext {
   /**
-   * The options provided to the Powerlines process
-   */
-  options: ExecutionOptions;
-  /**
-   * The input options used to initialize the context, which may be used when cloning the context to ensure the same configuration is applied to the new context
+   * The options provided to the Powerlines process, resolved with default values and merged with any configuration provided by plugins or other sources. This is typically the final configuration used during the build process, but may also include additional options that are relevant to the context and its interactions with the Powerlines engine.
    */
-  initialOptions: Partial<EngineOptions>;
-  /**
-   * The initial configuration provided when initializing the context, which may be used during the setup process to ensure that the configuration is properly merged and applied to the context. This is typically the user configuration provided in the Powerlines configuration file, but may also include additional configuration options provided by plugins or other sources.
-   */
-  initialConfig: InitialConfig<TResolvedConfig["userConfig"]>;
+  options: RequiredKeys<ExecutionOptions, "mode" | "cwd" | "root" | "framework" | "logLevel">;
   /**
    * An object containing the options provided to Powerlines
    */
-  config: Omit<TResolvedConfig["userConfig"], "output"> & Required<Pick<TResolvedConfig["userConfig"], "output">> & {
+  config: Omit<TResolvedConfig["userConfig"], "output"> & Required<Pick<TResolvedConfig["userConfig"], "output">> & Pick<TResolvedConfig, "cwd" | "root" | "mode" | "framework" | "configFile" | "name"> & {
+    /**
+     * The output configuration options for the Powerlines process, which may include settings related to the output directory, file naming conventions, and other options that affect how the compiled output is generated and structured. This is typically derived from the user configuration but may also include additional options provided by plugins or other sources.
+     */
     output: TResolvedConfig["output"];
+    /**
+     * The original configuration options that were provided by the user to the Powerlines process, which may be used during the configuration resolution process to ensure that the final configuration is properly merged and applied to the context. This is typically the user configuration provided in the Powerlines configuration file, but may also include additional configuration options provided by plugins or other sources.
+     */
+    readonly initialConfig: DeepReadonly<TResolvedConfig["initialConfig"]>;
+    /**
+     * The configuration options that were provided inline to the Powerlines CLI.
+     */
+    readonly inlineConfig: DeepReadonly<TResolvedConfig["inlineConfig"]>;
   };
   /**
    * The metadata information
@@ -319,31 +330,31 @@ interface UnresolvedContext<TResolvedConfig extends ResolvedConfig = ResolvedCon
   /**
    * The path to a directory where the reflection data buffers (used by the build processes) are stored
    */
-  dataPath: string;
+  readonly dataPath: string;
   /**
    * The path to a directory where the project cache (used by the build processes) is stored
    */
-  cachePath: string;
+  readonly cachePath: string;
   /**
    * The Powerlines artifacts directory
    */
-  artifactsPath: string;
+  readonly artifactsPath: string;
   /**
    * The path to the Powerlines builtin runtime modules directory
    */
-  builtinsPath: string;
+  readonly builtinsPath: string;
   /**
    * The path to the Powerlines entry modules directory
    */
-  entryPath: string;
+  readonly entryPath: string;
   /**
    * The path to the Powerlines infrastructure modules directory
    */
-  infrastructurePath: string;
+  readonly infrastructurePath: string;
   /**
    * The path to the Powerlines TypeScript declaration files directory
    */
-  typesPath: string;
+  readonly typesPath: string;
   /**
    * The project's `package.json` file content
    */
@@ -551,23 +562,12 @@ type Context<TResolvedConfig extends ResolvedConfig = ResolvedConfig> = Omit<Unr
    * The fully resolved Powerlines configuration
    */
   config: TResolvedConfig;
-  /**
-   * Initialize the context with the provided configuration options
-   */
-  setup: () => Promise<void>;
-  /**
-   * A function to create a deep clone of the context
-   *
-   * @remarks
-   * This function is used to create a copy of the context for a specific environment, allowing for environment-specific modifications without affecting the global context.
-   */
-  clone: () => Promise<Context<TResolvedConfig>>;
 };
 interface ExecutionContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig> {
   /**
    * The unique identifier of the execution context, which can be used for logging and other purposes to distinguish between different executions in the same process.
    */
-  id: string;
+  readonly id: string;
   /**
    * The expected plugins options for the Powerlines project.
    *
@@ -575,14 +575,14 @@ interface ExecutionContext<TResolvedConfig extends ResolvedConfig = ResolvedConf
    * 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>>;
+  /**
+   * A function to add a plugin to the context and update the configuration options
+   */
+  addPlugin: (plugin: Plugin<PluginContext<TResolvedConfig>>) => Promise<void>;
   /**
    * Retrieves the context for a specific environment by name
    *
@@ -632,26 +632,19 @@ interface ExecutionContext<TResolvedConfig extends ResolvedConfig = ResolvedConf
    * @param environment - The environment configuration to use.
    * @returns A new context instance with the updated environment.
    */
-  in: (environment: EnvironmentResolvedConfig) => Promise<EnvironmentContext<TResolvedConfig>>;
+  createEnvironment: (environment: EnvironmentResolvedConfig<TResolvedConfig>["environment"]) => 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>>;
-  /**
-   * A function to create a deep clone of the context
-   *
-   * @remarks
-   * This function is used to create a copy of the context for a specific environment, allowing for environment-specific modifications without affecting the global context.
-   */
-  clone: () => Promise<ExecutionContext<TResolvedConfig>>;
 }
 interface EnvironmentContextPlugin<TResolvedConfig extends ResolvedConfig = ResolvedConfig> {
   /**
    * The unique identifier of the plugin, which can be used for logging and other purposes to distinguish between different plugins in the same process.
    */
-  pluginId: string;
+  readonly id: string;
   /**
    * The plugin instance associated with this context, which can be used to access the plugin's options and other properties.
    */
@@ -668,11 +661,11 @@ type SelectHookResultItem<TContext extends PluginContext, TKey extends string> =
   context: TContext;
 };
 type SelectHookResult<TContext extends PluginContext, TKey extends string> = SelectHookResultItem<TContext, TKey>[];
-interface EnvironmentContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig> {
+interface EnvironmentContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<EnvironmentResolvedConfig<TResolvedConfig>> {
   /**
    * The unique identifier of the environment associated with this context, which can be used for logging and other purposes to distinguish between different environments in the same process.
    */
-  id: string;
+  readonly id: string;
   /**
    * The expected plugins options for the Powerlines project.
    *
@@ -680,46 +673,35 @@ interface EnvironmentContext<TResolvedConfig extends ResolvedConfig = ResolvedCo
    * 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
+   * A function to add a plugin to the context and update the configuration options
    */
-  selectHooks: <TKey extends string>(key: TKey, options?: SelectHooksOptions) => SelectHookResult<PluginContext<TResolvedConfig>, TKey>;
+  addPlugin: (plugin: Plugin<PluginContext<TResolvedConfig>>) => Promise<void>;
   /**
-   * A function to create a deep clone of the context
-   *
-   * @remarks
-   * This function is used to create a copy of the context for a specific environment, allowing for environment-specific modifications without affecting the global context.
+   * Retrieves the hook handlers for a specific hook name
    */
-  clone: () => Promise<EnvironmentContext<TResolvedConfig>>;
+  selectHooks: <TKey extends string>(key: TKey, options?: SelectHooksOptions) => SelectHookResult<PluginContext<TResolvedConfig>, TKey>;
 }
-interface PluginContext<out TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig> {
+interface PluginContext<out TResolvedConfig extends ResolvedConfig = ResolvedConfig, TApi extends API<any> = API<any>> extends Context<EnvironmentResolvedConfig<TResolvedConfig>> {
   /**
    * The unique identifier of the plugin associated with this context, which can be used for logging and other purposes to distinguish between different plugins in the same process.
    */
-  id: string;
-  /**
-   * The environment specific resolved configuration
-   */
-  environment: EnvironmentResolvedConfig;
+  readonly id: string;
   /**
-   * A function to create a deep clone of the context
+   * The API instance available to the plugin during execution, which provides access to the shared context and the ability to call plugin hooks. This API is specific to the plugin and environment, allowing for environment-specific interactions with the Powerlines engine.
    *
    * @remarks
-   * This function is used to create a copy of the context for a specific environment, allowing for environment-specific modifications without affecting the global context.
+   * The API instance provided in the plugin context may include additional functionality specific to command execution, and it extends the base API with any additional methods or properties that are relevant to the plugin's interactions with the Powerlines engine.
+   */
+  readonly api: TApi;
+  /**
+   * The context for the environment associated with this plugin context, which provides access to the Powerlines engine and other utilities for interacting with the build process. This context is specific to the plugin and environment, allowing for environment-specific modifications without affecting the global context.
    */
-  clone: () => Promise<PluginContext<TResolvedConfig>>;
+  readonly environment: EnvironmentContext;
 }
 type BuildPluginContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> = UnpluginBuildContext & PluginContext<TResolvedConfig>;
 type WithUnpluginBuildContext<TContext extends PluginContext> = UnpluginBuildContext & TContext;

package/dist/types/context.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.cts","names":[],"sources":["../../src/types/context.ts"],"mappings":"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"}
+{"version":3,"file":"context.d.cts","names":[],"sources":["../../src/types/context.ts"],"mappings":"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"}

package/dist/types/context.d.mts

@@ -1,11 +1,13 @@
-import { ResolveOptions, VirtualFile, VirtualFileSystemInterface, WriteOptions } from "./fs.mjs";
 import { Plugin } from "./plugin.mjs";
 import { HooksList, HooksListItem } from "./hooks.mjs";
+import { API } from "./api.mjs";
+import { ResolveOptions, VirtualFile, VirtualFileSystemInterface, WriteOptions } from "./fs.mjs";
 import { LogFn, LogLevelResolvedConfig, LogMessage, Logger, LoggerOptions } from "./logging.mjs";
 import { ParsedTypeScriptConfig } from "./tsconfig.mjs";
-import { EngineOptions, EnvironmentResolvedConfig, ExecutionOptions, InitialConfig, ParsedUserConfig, ResolvedConfig, ResolvedEntryTypeDefinition } from "./config.mjs";
+import { EngineOptions, EnvironmentResolvedConfig, ExecutionOptions, ParsedUserConfig, ResolvedConfig, ResolvedEntryTypeDefinition, UserConfig } from "./config.mjs";
 import { ExternalIdResult, UnpluginBuildContext } from "unplugin";
 import MagicString, { SourceMap } from "magic-string";
+import { DeepPartial, DeepReadonly, RequiredKeys } from "@stryke/types/base";
 import { Jiti } from "jiti";
 import { EnvPaths } from "@stryke/env/get-env-paths";
 import { FetchRequestOptions } from "@stryke/http/fetch";
@@ -136,10 +138,6 @@ interface ResolveResult extends ExternalIdResult {
  * This context provides the foundational structure for interacting with the Powerlines engine.
  */
 interface BaseContext {
-  /**
-   * The options provided to the Powerlines process
-   */
-  options: EngineOptions;
   /**
    * The timestamp when the context was initialized
    */
@@ -157,9 +155,9 @@ interface BaseContext {
    */
   configFile: ParsedUserConfig;
   /**
-   * The initial configuration provided when initializing the context, which may be used during the setup process to ensure that the configuration is properly merged and applied to the context. This is typically the user configuration provided in the Powerlines configuration file, but may also include additional configuration options provided by plugins or other sources.
+   * The options provided to the Powerlines process, resolved with default values and merged with any configuration provided by plugins or other sources. This is typically the final configuration used during the build process, but may also include additional options that are relevant to the context and its interactions with the Powerlines engine.
    */
-  initialConfig: InitialConfig<any>;
+  options: RequiredKeys<EngineOptions, "mode" | "cwd" | "root" | "framework">;
   /**
    * The log level to use for the Powerlines processes.
    */
@@ -220,13 +218,6 @@ interface BaseContext {
    * @returns A logger client instance that extends the current logger with the provided configuration options.
    */
   extendLogger: (options: LoggerOptions, logFn?: LogFn) => Logger;
-  /**
-   * A function to create a deep clone of the context
-   *
-   * @remarks
-   * This function is used to create a copy of the context for a specific environment, allowing for environment-specific modifications without affecting the global context.
-   */
-  clone: () => Promise<BaseContext>;
 }
 interface ExecutionStateItem {
   /**
@@ -278,6 +269,23 @@ interface ExecutionState {
  * This context is used during the execution of the Powerlines engine, providing access to the input user configurations.
  */
 interface EngineContext extends BaseContext {
+  /**
+   * The initial options provided to the Powerlines process before any resolution or merging. This is typically the user configuration provided in the Powerlines configuration file, but may also include additional configuration options provided by plugins or other sources.
+   */
+  readonly initialOptions: EngineOptions;
+  /**
+   * The options provided to the Powerlines process
+   */
+  options: RequiredKeys<Omit<EngineOptions, "logLevel">, "name" | "root" | "cwd" | "mode" | "framework"> & {
+    /**
+     * The log level to use for logging messages during the build process. This can be a string indicating the log level or a more detailed configuration object that allows for specifying different log levels for different categories of logs.
+     */
+    logLevel: LogLevelResolvedConfig;
+  };
+  /**
+   * The initial user configuration provided to the Powerlines process before any resolution or merging. This is typically the user configuration provided in the Powerlines configuration file, but may also include additional configuration options provided by plugins or other sources.
+   */
+  readonly initialConfig: DeepPartial<UserConfig>;
   /**
    * A list of all command executions that will be run during the lifecycle of the engine
    */
@@ -291,22 +299,25 @@ interface EngineContext extends BaseContext {
  */
 interface UnresolvedContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends BaseContext {
   /**
-   * The options provided to the Powerlines process
-   */
-  options: ExecutionOptions;
-  /**
-   * The input options used to initialize the context, which may be used when cloning the context to ensure the same configuration is applied to the new context
+   * The options provided to the Powerlines process, resolved with default values and merged with any configuration provided by plugins or other sources. This is typically the final configuration used during the build process, but may also include additional options that are relevant to the context and its interactions with the Powerlines engine.
    */
-  initialOptions: Partial<EngineOptions>;
-  /**
-   * The initial configuration provided when initializing the context, which may be used during the setup process to ensure that the configuration is properly merged and applied to the context. This is typically the user configuration provided in the Powerlines configuration file, but may also include additional configuration options provided by plugins or other sources.
-   */
-  initialConfig: InitialConfig<TResolvedConfig["userConfig"]>;
+  options: RequiredKeys<ExecutionOptions, "mode" | "cwd" | "root" | "framework" | "logLevel">;
   /**
    * An object containing the options provided to Powerlines
    */
-  config: Omit<TResolvedConfig["userConfig"], "output"> & Required<Pick<TResolvedConfig["userConfig"], "output">> & {
+  config: Omit<TResolvedConfig["userConfig"], "output"> & Required<Pick<TResolvedConfig["userConfig"], "output">> & Pick<TResolvedConfig, "cwd" | "root" | "mode" | "framework" | "configFile" | "name"> & {
+    /**
+     * The output configuration options for the Powerlines process, which may include settings related to the output directory, file naming conventions, and other options that affect how the compiled output is generated and structured. This is typically derived from the user configuration but may also include additional options provided by plugins or other sources.
+     */
     output: TResolvedConfig["output"];
+    /**
+     * The original configuration options that were provided by the user to the Powerlines process, which may be used during the configuration resolution process to ensure that the final configuration is properly merged and applied to the context. This is typically the user configuration provided in the Powerlines configuration file, but may also include additional configuration options provided by plugins or other sources.
+     */
+    readonly initialConfig: DeepReadonly<TResolvedConfig["initialConfig"]>;
+    /**
+     * The configuration options that were provided inline to the Powerlines CLI.
+     */
+    readonly inlineConfig: DeepReadonly<TResolvedConfig["inlineConfig"]>;
   };
   /**
    * The metadata information
@@ -319,31 +330,31 @@ interface UnresolvedContext<TResolvedConfig extends ResolvedConfig = ResolvedCon
   /**
    * The path to a directory where the reflection data buffers (used by the build processes) are stored
    */
-  dataPath: string;
+  readonly dataPath: string;
   /**
    * The path to a directory where the project cache (used by the build processes) is stored
    */
-  cachePath: string;
+  readonly cachePath: string;
   /**
    * The Powerlines artifacts directory
    */
-  artifactsPath: string;
+  readonly artifactsPath: string;
   /**
    * The path to the Powerlines builtin runtime modules directory
    */
-  builtinsPath: string;
+  readonly builtinsPath: string;
   /**
    * The path to the Powerlines entry modules directory
    */
-  entryPath: string;
+  readonly entryPath: string;
   /**
    * The path to the Powerlines infrastructure modules directory
    */
-  infrastructurePath: string;
+  readonly infrastructurePath: string;
   /**
    * The path to the Powerlines TypeScript declaration files directory
    */
-  typesPath: string;
+  readonly typesPath: string;
   /**
    * The project's `package.json` file content
    */
@@ -551,23 +562,12 @@ type Context<TResolvedConfig extends ResolvedConfig = ResolvedConfig> = Omit<Unr
    * The fully resolved Powerlines configuration
    */
   config: TResolvedConfig;
-  /**
-   * Initialize the context with the provided configuration options
-   */
-  setup: () => Promise<void>;
-  /**
-   * A function to create a deep clone of the context
-   *
-   * @remarks
-   * This function is used to create a copy of the context for a specific environment, allowing for environment-specific modifications without affecting the global context.
-   */
-  clone: () => Promise<Context<TResolvedConfig>>;
 };
 interface ExecutionContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig> {
   /**
    * The unique identifier of the execution context, which can be used for logging and other purposes to distinguish between different executions in the same process.
    */
-  id: string;
+  readonly id: string;
   /**
    * The expected plugins options for the Powerlines project.
    *
@@ -575,14 +575,14 @@ interface ExecutionContext<TResolvedConfig extends ResolvedConfig = ResolvedConf
    * 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>>;
+  /**
+   * A function to add a plugin to the context and update the configuration options
+   */
+  addPlugin: (plugin: Plugin<PluginContext<TResolvedConfig>>) => Promise<void>;
   /**
    * Retrieves the context for a specific environment by name
    *
@@ -632,26 +632,19 @@ interface ExecutionContext<TResolvedConfig extends ResolvedConfig = ResolvedConf
    * @param environment - The environment configuration to use.
    * @returns A new context instance with the updated environment.
    */
-  in: (environment: EnvironmentResolvedConfig) => Promise<EnvironmentContext<TResolvedConfig>>;
+  createEnvironment: (environment: EnvironmentResolvedConfig<TResolvedConfig>["environment"]) => 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>>;
-  /**
-   * A function to create a deep clone of the context
-   *
-   * @remarks
-   * This function is used to create a copy of the context for a specific environment, allowing for environment-specific modifications without affecting the global context.
-   */
-  clone: () => Promise<ExecutionContext<TResolvedConfig>>;
 }
 interface EnvironmentContextPlugin<TResolvedConfig extends ResolvedConfig = ResolvedConfig> {
   /**
    * The unique identifier of the plugin, which can be used for logging and other purposes to distinguish between different plugins in the same process.
    */
-  pluginId: string;
+  readonly id: string;
   /**
    * The plugin instance associated with this context, which can be used to access the plugin's options and other properties.
    */
@@ -668,11 +661,11 @@ type SelectHookResultItem<TContext extends PluginContext, TKey extends string> =
   context: TContext;
 };
 type SelectHookResult<TContext extends PluginContext, TKey extends string> = SelectHookResultItem<TContext, TKey>[];
-interface EnvironmentContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig> {
+interface EnvironmentContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<EnvironmentResolvedConfig<TResolvedConfig>> {
   /**
    * The unique identifier of the environment associated with this context, which can be used for logging and other purposes to distinguish between different environments in the same process.
    */
-  id: string;
+  readonly id: string;
   /**
    * The expected plugins options for the Powerlines project.
    *
@@ -680,46 +673,35 @@ interface EnvironmentContext<TResolvedConfig extends ResolvedConfig = ResolvedCo
    * 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
+   * A function to add a plugin to the context and update the configuration options
    */
-  selectHooks: <TKey extends string>(key: TKey, options?: SelectHooksOptions) => SelectHookResult<PluginContext<TResolvedConfig>, TKey>;
+  addPlugin: (plugin: Plugin<PluginContext<TResolvedConfig>>) => Promise<void>;
   /**
-   * A function to create a deep clone of the context
-   *
-   * @remarks
-   * This function is used to create a copy of the context for a specific environment, allowing for environment-specific modifications without affecting the global context.
+   * Retrieves the hook handlers for a specific hook name
    */
-  clone: () => Promise<EnvironmentContext<TResolvedConfig>>;
+  selectHooks: <TKey extends string>(key: TKey, options?: SelectHooksOptions) => SelectHookResult<PluginContext<TResolvedConfig>, TKey>;
 }
-interface PluginContext<out TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig> {
+interface PluginContext<out TResolvedConfig extends ResolvedConfig = ResolvedConfig, TApi extends API<any> = API<any>> extends Context<EnvironmentResolvedConfig<TResolvedConfig>> {
   /**
    * The unique identifier of the plugin associated with this context, which can be used for logging and other purposes to distinguish between different plugins in the same process.
    */
-  id: string;
-  /**
-   * The environment specific resolved configuration
-   */
-  environment: EnvironmentResolvedConfig;
+  readonly id: string;
   /**
-   * A function to create a deep clone of the context
+   * The API instance available to the plugin during execution, which provides access to the shared context and the ability to call plugin hooks. This API is specific to the plugin and environment, allowing for environment-specific interactions with the Powerlines engine.
    *
    * @remarks
-   * This function is used to create a copy of the context for a specific environment, allowing for environment-specific modifications without affecting the global context.
+   * The API instance provided in the plugin context may include additional functionality specific to command execution, and it extends the base API with any additional methods or properties that are relevant to the plugin's interactions with the Powerlines engine.
+   */
+  readonly api: TApi;
+  /**
+   * The context for the environment associated with this plugin context, which provides access to the Powerlines engine and other utilities for interacting with the build process. This context is specific to the plugin and environment, allowing for environment-specific modifications without affecting the global context.
    */
-  clone: () => Promise<PluginContext<TResolvedConfig>>;
+  readonly environment: EnvironmentContext;
 }
 type BuildPluginContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> = UnpluginBuildContext & PluginContext<TResolvedConfig>;
 type WithUnpluginBuildContext<TContext extends PluginContext> = UnpluginBuildContext & TContext;