@teambit/envs 1.0.228 → 1.0.230

package/dist/environments.main.runtime.d.ts

@@ -0,0 +1,320 @@
+import { SourceFile } from '@teambit/legacy/dist/consumer/component/sources';
+import { CLIMain } from '@teambit/cli';
+import { Component, ComponentMain } from '@teambit/component';
+import { GraphqlMain } from '@teambit/graphql';
+import { IssuesMain } from '@teambit/issues';
+import { Harmony, SlotRegistry } from '@teambit/harmony';
+import { Logger, LoggerMain } from '@teambit/logger';
+import { ExtensionDataList } from '@teambit/legacy/dist/consumer/config/extension-data';
+import { WorkerMain } from '@teambit/worker';
+import { ComponentID } from '@teambit/component-id';
+import { EnvService } from './services';
+import { Environment } from './environment';
+import { Runtime } from './runtime';
+import { EnvDefinition } from './env-definition';
+import { EnvServiceList } from './env-service-list';
+import { EnvPlugin } from './env.plugin';
+export type EnvsRegistry = SlotRegistry<Environment>;
+export type EnvsConfig = {
+    env: string;
+    options: EnvOptions;
+};
+type GetCalcEnvOptions = {
+    skipWarnings?: boolean;
+};
+export type EnvOptions = {};
+export type EnvTransformer = (env: Environment) => Environment;
+export type ServicesRegistry = SlotRegistry<Array<EnvService<any>>>;
+export type RegularCompDescriptor = {
+    id: string;
+    icon?: string;
+    type?: string;
+    name?: string;
+    description?: string;
+};
+export type EnvCompDescriptorProps = RegularCompDescriptor & {
+    services?: {
+        env: {
+            id: string;
+            icon: string;
+            name?: string;
+            description?: string;
+        };
+        services: Array<{
+            id: string;
+            name?: string;
+            description?: string;
+            data: any;
+        }>;
+    };
+};
+export type EnvCompDescriptor = EnvCompDescriptorProps & {
+    self?: EnvCompDescriptorProps;
+};
+export type Descriptor = RegularCompDescriptor | EnvCompDescriptor;
+export declare const DEFAULT_ENV = "teambit.harmony/node";
+export declare class EnvsMain {
+    /**
+     * environments extension configuration.
+     */
+    readonly config: EnvsConfig;
+    /**
+     * harmony context.
+     */
+    private harmony;
+    /**
+     * slot for allowing extensions to register new environment.
+     */
+    private envSlot;
+    private logger;
+    private servicesRegistry;
+    private componentMain;
+    private loggerMain;
+    private workerMain;
+    /**
+     * Envs that are failed to load
+     */
+    private failedToLoadEnvs;
+    /**
+     * Extensions that are failed to load
+     * We use this as sometime when we couldn't load an extension we don't know if it's an env or not
+     * We should ideally take it from the aspect loader aspect, but right now the aspect loader is using envs
+     */
+    private failedToLoadExt;
+    /**
+     * Ids of envs (not neccesrraly loaded successfully)
+     */
+    envIds: Set<string>;
+    static runtime: import("@teambit/bit").RuntimeDefinition;
+    private alreadyShownWarning;
+    /**
+     * icon of the extension.
+     */
+    icon(): string;
+    constructor(
+    /**
+     * environments extension configuration.
+     */
+    config: EnvsConfig, 
+    /**
+     * harmony context.
+     */
+    harmony: Harmony, 
+    /**
+     * slot for allowing extensions to register new environment.
+     */
+    envSlot: EnvsRegistry, logger: Logger, servicesRegistry: ServicesRegistry, componentMain: ComponentMain, loggerMain: LoggerMain, workerMain: WorkerMain);
+    /**
+     * creates a new runtime environments for a set of components.
+     */
+    createEnvironment(components: Component[]): Promise<Runtime>;
+    /**
+     *
+     * @param id
+     */
+    /**
+     * This function adds an extension ID to a set of failed to load extensions.
+     * This mostly used by the aspect loader to add such issues
+     * Then it is used to hide different errors that are caused by the same issue.
+     * @param {string} id - string - represents the unique identifier of an extension that failed to load.
+     */
+    addFailedToLoadEnvs(id: string): void;
+    addFailedToLoadExt(id: string): void;
+    resetFailedToLoadEnvs(): void;
+    getFailedToLoadEnvs(): string[];
+    /**
+     * get the configured default env.
+     */
+    getDefaultEnv(): EnvDefinition;
+    getCoreEnvsIds(): string[];
+    /**
+     * compose a new environment from a list of environment transformers.
+     */
+    compose(targetEnv: Environment, envTransformers: EnvTransformer[]): Environment;
+    /**
+     * create an env transformer which overrides specific env properties.
+     */
+    override(propsToOverride: Environment): EnvTransformer;
+    /**
+     * compose two environments into one.
+     */
+    merge<T extends Environment, S extends Environment>(targetEnv: Environment, sourceEnv: Environment): T & S;
+    /**
+     * This function checks if an environment manifest file exists in a given component or set of legacy files.
+     * @param {Component} [envComponent] - A component object that represents an environment. It contains information about
+     * the files and directories that make up the environment.
+     * @param {SourceFile[]} [legacyFiles] - An optional array of SourceFile objects representing the files in the legacy
+     * file system. If this parameter is not provided, the function will attempt to retrieve the files from the envComponent
+     * parameter.
+     * @returns a boolean value indicating whether an `env.jsonc` or `env.json` file exists in the `files` array of either
+     * the `envComponent` object or the `legacyFiles` array. If neither `envComponent` nor `legacyFiles` are provided, the
+     * function returns `undefined`.
+     */
+    hasEnvManifest(envComponent?: Component, legacyFiles?: SourceFile[]): boolean | undefined;
+    getEnvManifest(envComponent?: Component, legacyFiles?: SourceFile[]): Object | undefined;
+    hasEnvManifestById(envId: string, requesting: string): Promise<boolean | undefined>;
+    getEnvData(component: Component): Descriptor;
+    /**
+     * Return the id of the env as configured in the envs data (without version by default)
+     * The reason it's not contain version by default is that we want to take the version from the aspect defined on the component itself
+     * As this version is stay up to date during tagging the env along with the component
+     * @param component
+     * @param ignoreVersion
+     */
+    private getEnvIdFromEnvsData;
+    /**
+     * get the env id of the given component.
+     */
+    getEnvId(component: Component): string;
+    isUsingCoreEnv(component: Component): boolean;
+    isCoreEnv(envId: string): boolean;
+    /**
+     * get the env of the given component.
+     * In case you are asking for the env during on load you should use calculateEnv instead
+     */
+    getEnv(component: Component): EnvDefinition;
+    /**
+     * get the env component of the given component.
+     */
+    getEnvComponent(component: Component): Promise<Component>;
+    /**
+     * get the env component by the env id.
+     */
+    getEnvComponentByEnvId(envId: string, requesting?: string): Promise<Component>;
+    /**
+     * get the env of the given component.
+     * This will try to use the regular getEnv but fallback to the calculate env (in case you are using it during on load)
+     * This is safe to be used on onLoad as well
+     */
+    getOrCalculateEnv(component: Component): EnvDefinition;
+    /**
+     * get an environment Descriptor.
+     */
+    getDescriptor(component: Component): Descriptor | undefined;
+    calcDescriptor(component: Component, opts?: GetCalcEnvOptions): Promise<Descriptor | undefined>;
+    /**
+     * Get env descriptor from the env itself if the component is an env
+     * This will be empty for regular component, and will only contain data for env themself
+     */
+    private getEnvSelfDescriptor;
+    /**
+     * Get env descriptor from the env that a given component is using
+     */
+    private getComponentEnvDescriptor;
+    private getEnvDescriptorFromEnvDef;
+    resolveEnv(component: Component, id: string): ComponentID | undefined;
+    /**
+     * This used to calculate the actual env during the component load.
+     * Do not use it to get the env (use getEnv instead)
+     * This should be used only during on load
+     */
+    calculateEnvId(component: Component): Promise<ComponentID>;
+    /**
+     * This used to calculate the actual env during the component load.
+     * Do not use it to get the env (use getEnv instead)
+     * This should be used only during on load
+     */
+    calculateEnv(component: Component, opts?: GetCalcEnvOptions): EnvDefinition;
+    /**
+     * an env can be configured on a component in two ways:
+     * 1) explicitly inside "teambit.envs/envs". `{ "teambit.envs/envs": { "env": "my-env" } }`
+     * 2) the env aspect is set on the variant as any other aspect, e.g. `{ "my-env": {} }`
+     *
+     * this method returns #1 if exists, otherwise, #2.
+     */
+    getAllEnvsConfiguredOnComponent(component: Component): EnvDefinition[];
+    /**
+     * whether a component has an env configured (either by variant or .bitmap).
+     */
+    hasEnvConfigured(component: Component): boolean;
+    getAllRegisteredEnvs(): string[];
+    getEnvPlugin(): EnvPlugin;
+    /**
+     * an env can be configured on a component in two ways:
+     * 1) explicitly inside "teambit.envs/envs". `{ "teambit.envs/envs": { "env": "my-env" } }`
+     * 2) the env aspect is set on the variant as any other aspect, e.g. `{ "my-env": {} }`
+     *
+     * this method returns only #1
+     */
+    getEnvFromEnvsConfig(component: Component): EnvDefinition | undefined;
+    /**
+     * an env can be configured on a component in two ways:
+     * 1) explicitly inside "teambit.envs/envs". `{ "teambit.envs/envs": { "env": "my-env" } }`
+     * 2) the env aspect is set on the variant as any other aspect, e.g. `{ "my-env": {} }`
+     *
+     * this method returns only #2
+     */
+    getEnvsNotFromEnvsConfig(component: Component): EnvDefinition[];
+    getEnvIdFromEnvsLegacyExtensions(extensions: ExtensionDataList): string | undefined;
+    /**
+     * @deprecated DO NOT USE THIS METHOD ANYMORE!!! (PLEASE USE .calculateEnvId() instead!)
+     */
+    calculateEnvIdFromExtensions(extensions: ExtensionDataList): Promise<string>;
+    /**
+     * @deprecated DO NOT USE THIS METHOD ANYMORE!!! (PLEASE USE .calculateEnv() instead!)
+     */
+    calculateEnvFromExtensions(extensions: ExtensionDataList): Promise<EnvDefinition>;
+    /**
+     * This function finds the first environment ID from a list of IDs by checking if it is register as env (to the slot).
+     * or contains env.jsonc file
+     * @param {string[]} ids - `ids` is an array of string values representing environment IDs. The function `findFirstEnv`
+     * takes this array as input and returns a Promise that resolves to a string value representing the first environment ID
+     * that matches certain conditions.
+     * @returns The `findFirstEnv` function returns a Promise that resolves to a string or undefined. The string represents
+     * the ID of the first environment that matches the conditions specified in the function, or undefined if no environment
+     * is found.
+     */
+    private findFirstEnv;
+    private getEnvDefinitionByLegacyExtension;
+    getEnvIdFromEnvsConfig(component: Component): string | undefined;
+    getEnvDefinition(id: ComponentID): EnvDefinition | undefined;
+    getEnvDefinitionById(id: ComponentID): EnvDefinition | undefined;
+    getEnvDefinitionByStringId(envId: string): EnvDefinition | undefined;
+    getEnvFromComponent(envComponent: Component): EnvDefinition | undefined;
+    /**
+     * Return the env definition of teambit.envs/env
+     */
+    getEnvsEnvDefinition(): EnvDefinition;
+    private printWarningIfFirstTime;
+    /**
+     * determines whether an env is registered.
+     */
+    isEnvRegistered(id: string): boolean;
+    isUsingAspectEnv(component: Component): boolean;
+    isUsingEnvEnv(component: Component): boolean;
+    /**
+     * Check if the given component is an env component.
+     * @param component
+     * @returns
+     */
+    isEnv(component: Component): boolean;
+    /**
+     * register a new environment service.
+     */
+    registerService(...envServices: EnvService<any>[]): this;
+    /**
+     * get list of services enabled on an env.
+     */
+    getServices(env: EnvDefinition): EnvServiceList;
+    implements(env: EnvDefinition, service: EnvService<any>): boolean;
+    /**
+     * register an environment.
+     */
+    registerEnv(env: Environment): void;
+    addNonLoadedEnvAsComponentIssues(components: Component[]): Promise<void>;
+    private createRuntime;
+    private aggregateByDefs;
+    private getEnvAspectDef;
+    private throwForDuplicateComponents;
+    static slots: (((registerFn: () => string) => SlotRegistry<Environment>) | ((registerFn: () => string) => SlotRegistry<EnvService<any, {}, {}>>))[];
+    static dependencies: import("@teambit/bit").Aspect[];
+    static provider([graphql, loggerAspect, component, cli, worker, issues]: [
+        GraphqlMain,
+        LoggerMain,
+        ComponentMain,
+        CLIMain,
+        WorkerMain,
+        IssuesMain
+    ], config: EnvsConfig, [envSlot, servicesRegistry]: [EnvsRegistry, ServicesRegistry], context: Harmony): Promise<EnvsMain>;
+}
+export {};

package/dist/envs.cmd.d.ts

@@ -0,0 +1,51 @@
+import { Command, CommandOptions } from '@teambit/cli';
+import { ComponentMain, ComponentFactory } from '@teambit/component';
+import { EnvsMain } from './environments.main.runtime';
+export declare class ListEnvsCmd implements Command {
+    private envs;
+    private componentAspect;
+    name: string;
+    description: string;
+    options: never[];
+    group: string;
+    constructor(envs: EnvsMain, componentAspect: ComponentMain);
+    report(): Promise<string>;
+}
+type GetEnvOpts = {
+    services: string;
+};
+export declare class GetEnvCmd implements Command {
+    private envs;
+    private componentAspect;
+    name: string;
+    description: string;
+    arguments: {
+        name: string;
+        description: string;
+    }[];
+    examples: [{
+        cmd: 'get ui/button';
+        description: 'show config information from the env configured for ui/button';
+    }];
+    options: CommandOptions;
+    group: string;
+    constructor(envs: EnvsMain, componentAspect: ComponentMain);
+    showEnv(id: string, host: ComponentFactory, servicesArr: string[] | undefined): Promise<string>;
+    report([name]: [string], { services }: GetEnvOpts): Promise<string>;
+}
+export declare class EnvsCmd implements Command {
+    private envs;
+    private componentAspect;
+    name: string;
+    alias: string;
+    description: string;
+    options: never[];
+    group: string;
+    commands: Command[];
+    private nonLoadedEnvs;
+    constructor(envs: EnvsMain, componentAspect: ComponentMain);
+    report(): Promise<string>;
+    private getTable;
+    getNonLoadedEnvsWarning(): string;
+}
+export {};

package/dist/exceptions/env-not-configured-for-component.d.ts

@@ -0,0 +1,4 @@
+import { BitError } from '@teambit/bit-error';
+export declare class EnvNotConfiguredForComponent extends BitError {
+    constructor(id: string, componentId?: string);
+}

package/dist/exceptions/env-not-found-in-runtime.d.ts

@@ -0,0 +1,5 @@
+import { BitError } from '@teambit/bit-error';
+export declare class EnvNotFoundInRuntime extends BitError {
+    private id;
+    constructor(id: string);
+}

package/dist/exceptions/env-not-found.d.ts

@@ -0,0 +1,6 @@
+import { BitError } from '@teambit/bit-error';
+export declare class EnvNotFound extends BitError {
+    private id;
+    private componentId?;
+    constructor(id: string, componentId?: string | undefined);
+}

package/dist/exceptions/index.d.ts

@@ -0,0 +1,3 @@
+export { EnvNotFoundInRuntime } from './env-not-found-in-runtime';
+export { EnvNotFound } from './env-not-found';
+export { EnvNotConfiguredForComponent } from './env-not-configured-for-component';

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { EnvsAspect } from './environments.aspect';
+export { ServiceHandlerContext as EnvContext } from './services';
+export type { ServiceHandlerFactory as EnvHandler, AsyncServiceHandlerFactory as AsyncEnvHandler, ServiceHandler, ServiceTransformationMap, } from './services';
+export { DEFAULT_ENV } from './environments.main.runtime';
+export * from './environment';
+export { ExecutionContext } from './context';
+export type { EnvService, ConcreteService } from './services';
+export { reduceServiceHandlersFactories } from './services';
+export { EnvRuntime } from './runtime/env-runtime';
+export type { Env } from './env-interface';
+export type { EnvsMain, EnvTransformer, Descriptor, RegularCompDescriptor, EnvCompDescriptor, } from './environments.main.runtime';
+export { EnvsAspect };
+export { EnvsExecutionResult } from './runtime/envs-execution-result';
+export type { EnvServiceList } from './env-service-list';
+export { EnvDefinition } from './env-definition';
+export default EnvsAspect;

package/dist/{preview-1712805335812.js → preview-1712891953391.js}

@@ -1,5 +1,5 @@
-import * as compositions_0 from '/home/circleci/Library/Caches/Bit/capsules/8891be5ad3d35bfc38b9cd90c0e05b598a5a55af/teambit.envs_envs@1.0.228/dist/env.composition.js';
-import * as overview_0 from '/home/circleci/Library/Caches/Bit/capsules/8891be5ad3d35bfc38b9cd90c0e05b598a5a55af/teambit.envs_envs@1.0.228/dist/envs.docs.mdx';
+import * as compositions_0 from '/home/circleci/Library/Caches/Bit/capsules/8891be5ad3d35bfc38b9cd90c0e05b598a5a55af/teambit.envs_envs@1.0.230/dist/env.composition.js';
+import * as overview_0 from '/home/circleci/Library/Caches/Bit/capsules/8891be5ad3d35bfc38b9cd90c0e05b598a5a55af/teambit.envs_envs@1.0.230/dist/envs.docs.mdx';
 
 export const compositions = [compositions_0];
 export const overview = [overview_0];

package/dist/runtime/env-runtime.d.ts

@@ -0,0 +1,41 @@
+import { AspectDefinition } from '@teambit/aspect-loader';
+import { Component } from '@teambit/component';
+import { Environment } from '../environment';
+/**
+ * env runtime is an instance which represent the given env in a
+ */
+export declare class EnvRuntime {
+    /**
+     * ID of the wrapping extension.
+     */
+    readonly id: string;
+    /**
+     * environment
+     */
+    readonly env: Environment;
+    /**
+     * components to be loaded in the environment
+     */
+    readonly components: Component[];
+    /**
+     * Aspect definition of the env.
+     */
+    readonly envAspectDefinition: AspectDefinition;
+    constructor(
+    /**
+     * ID of the wrapping extension.
+     */
+    id: string, 
+    /**
+     * environment
+     */
+    env: Environment, 
+    /**
+     * components to be loaded in the environment
+     */
+    components: Component[], 
+    /**
+     * Aspect definition of the env.
+     */
+    envAspectDefinition: AspectDefinition);
+}

package/dist/runtime/envs-execution-result.d.ts

@@ -0,0 +1,18 @@
+import { ServiceExecutionResult } from '../services';
+import { EnvResult } from './runtime';
+export declare class EnvsExecutionResult<T extends ServiceExecutionResult> {
+    readonly results: EnvResult<T>[];
+    constructor(results: EnvResult<T>[]);
+    hasErrors(): boolean;
+    /**
+     * execution errors.
+     */
+    get errors(): Error[];
+    getErrorsOfEnv(envResult: EnvResult<T>): Error[];
+    /**
+     * if only one error is found, throw it. otherwise, summarize the errors per env and throw the
+     * output
+     */
+    throwErrorsIfExist(): void;
+    getEnvErrorsAsString(envResult: EnvResult<T>): string;
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,2 @@
+export { Runtime } from './runtime';
+export { EnvRuntime } from './env-runtime';

package/dist/runtime/runtime.d.ts

@@ -0,0 +1,49 @@
+import { Logger } from '@teambit/logger';
+import { ExecutionContext } from '../context';
+import { EnvService, ServiceExecutionResult } from '../services';
+import { EnvRuntime } from './env-runtime';
+import { EnvsExecutionResult } from './envs-execution-result';
+export interface EnvResult<T extends ServiceExecutionResult> {
+    env: EnvRuntime;
+    data?: T;
+    error?: Error;
+}
+export declare class Runtime {
+    /**
+     * runtime instances of the environments.
+     */
+    readonly runtimeEnvs: EnvRuntime[];
+    private logger;
+    constructor(
+    /**
+     * runtime instances of the environments.
+     */
+    runtimeEnvs: EnvRuntime[], logger: Logger);
+    /**
+     * execute a service on a specific env.
+     */
+    runEnv<T extends ServiceExecutionResult>(envRuntimeId: string, service: EnvService<T>, options?: {
+        [key: string]: any;
+    }): Promise<EnvsExecutionResult<T>>;
+    /**
+     * execute a service once for all environments.
+     */
+    runOnce<T extends ServiceExecutionResult>(service: EnvService<T>, options?: {
+        [key: string]: any;
+    }): Promise<any>;
+    getEnvExecutionContext(): ExecutionContext[];
+    /**
+     * execute a service on each one of the environments.
+     */
+    run<T extends ServiceExecutionResult>(
+    /**
+     * environment service to execute.
+     */
+    service: EnvService<T>, 
+    /**
+     * options to proxy to the service upon execution.
+     */
+    options?: {
+        [key: string]: any;
+    }, runtimes?: EnvRuntime[]): Promise<EnvsExecutionResult<T>>;
+}

package/dist/services/concrete-service.d.ts

@@ -0,0 +1,8 @@
+/**
+ * please do not use this.
+ * @deprecated
+ */
+export interface ConcreteService {
+    getPackageJsonProps?: () => Record<string, any>;
+    dependencies?: () => any;
+}

package/dist/services/index.d.ts

@@ -0,0 +1,4 @@
+export { Service as EnvService, ServiceExecutionResult, TransformationMap as ServiceTransformationMap, } from './service';
+export { ConcreteService } from './concrete-service';
+export { ServiceHandler, ServiceHandlerFactory, AsyncServiceHandlerFactory, reduceServiceHandlersFactories, } from './service-handler';
+export { ServiceHandlerContext } from './service-handler-context';

package/dist/services/service-handler-context.d.ts

@@ -0,0 +1,30 @@
+import { ComponentID } from '@teambit/component';
+import { Harmony } from '@teambit/harmony';
+import { Logger, LoggerMain } from '@teambit/logger';
+import { WorkerMain } from '@teambit/worker';
+export declare class ServiceHandlerContext {
+    /**
+     * id of the environment defined in the context.
+     */
+    readonly envId: ComponentID;
+    readonly loggerMain: LoggerMain;
+    readonly workerMain: WorkerMain;
+    readonly harmony: Harmony;
+    constructor(
+    /**
+     * id of the environment defined in the context.
+     */
+    envId: ComponentID, loggerMain: LoggerMain, workerMain: WorkerMain, harmony: Harmony);
+    /**
+     * return a logger instance for the env.
+     */
+    createLogger(name?: string): Logger;
+    /**
+     * get an instance of an aspect. make sure it is loaded prior to requesting it.
+     */
+    getAspect<T>(aspectId: string): T;
+    /**
+     * create worker for the env context.
+     */
+    createWorker<T>(name: string, path: string): import("@teambit/worker").HarmonyWorker<T>;
+}

package/dist/services/service-handler.d.ts

@@ -0,0 +1,18 @@
+import { ServiceHandlerContext } from './service-handler-context';
+/**
+ * definition of the service handler.
+ */
+export type ServiceHandlerFactory<T> = (context: ServiceHandlerContext) => ServiceHandler & T;
+export type AsyncServiceHandlerFactory<T> = (context: ServiceHandlerContext) => Promise<ServiceHandler & T>;
+export interface ServiceHandler {
+    /**
+     * name of the service. e.g. 'typescript-compiler'
+     */
+    name?: string;
+    /**
+     * version of the service. optional.
+     */
+    version?: () => string;
+}
+export type ReduceFactoryCallback<T> = (acc: T, value: T) => ServiceHandler & T;
+export declare function reduceServiceHandlersFactories<T>(factories: ServiceHandlerFactory<T>[], callback: ReduceFactoryCallback<T>): ServiceHandlerFactory<T>;

package/dist/services/service.d.ts

@@ -0,0 +1,66 @@
+import { Component } from '@teambit/component';
+import { Env } from '../env-interface';
+import { Environment } from '../environment';
+import { ServiceHandler } from './service-handler';
+import { ServiceHandlerContext } from './service-handler-context';
+export type EnvContext = {
+    components: Component[];
+};
+export interface ServiceExecutionResult {
+    errors?: Error[];
+}
+export type ServiceTransformHandlerFactory<T> = (handlerContext?: any) => (ServiceHandler & T) | Promise<ServiceHandler & T>;
+/**
+ * definition of the service handler type
+ * This used to define new types of handlers like
+ * Compiler, Tester, Preview, etc.
+ */
+export type TransformationMap = {
+    /**
+     * The name of the function that will be called on the service run/run once later.
+     * This func will be exist on the final env object
+     */
+    [funcName: string]: ServiceTransformHandlerFactory<any>;
+};
+/**
+ * services allows to reuse and standardize services for development environments.
+ * examples for services can be: `linting`, `compilation`, `build`, and others which offer
+ * standard services to environments such as `react`, `angular` and `vue` and different compositions of each for
+ * more concrete needs.
+ *
+ * `TData` - type of data returned by the service handler.
+ * `TOpts` is the type of options passed to the environment through execution.
+ * `TExecResponse` is the execution result of the service.
+ */
+export interface Service<TExecResponse extends ServiceExecutionResult, TData = {}, TOpts = {}> {
+    /**
+     * name of the service. (e.g. `compile`, `test`, etc.)
+     */
+    name?: string;
+    /**
+     * description of the env.
+     */
+    description?: string;
+    /**
+     * create a string to describe to service in the env cli.
+     */
+    render?(env: Environment, context: EnvContext[]): string | Promise<string>;
+    /**
+     * get service data from an environment.
+     */
+    getDescriptor?(environment: Environment, context?: EnvContext[]): TData | undefined | Promise<TData | undefined>;
+    /**
+     * executes a service on a subset of components.
+     */
+    run?(context: EnvContext, options?: TOpts): Promise<TExecResponse>;
+    /**
+     * run the service only once.
+     */
+    runOnce?(context: EnvContext[], options?: TOpts): Promise<any>;
+    /**
+     * Return a map of functions that will be called on the service run/run once later.
+     * @param env the original env plugin object
+     * @param context ServiceHandlerContext(EnvContext)
+     */
+    transform?(env: Env, context: ServiceHandlerContext): TransformationMap | undefined;
+}