@equinor/fusion-framework-cli 10.7.4 → 11.0.0-next.0

package/dist/types/{schemas.d.ts → lib/app/schemas.d.ts}

@@ -1,6 +1,9 @@
 import { z } from 'zod';
 /**
- * Api config object
+ * Zod schema for validating the API application configuration object.
+ *
+ * This schema defines the structure and types for the app config used in the Fusion Framework CLI.
+ * It ensures that the configuration adheres to expected types and provides sensible defaults.
  */
 export declare const ApiAppConfigSchema: z.ZodObject<{
     environment: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>>;
@@ -27,4 +30,10 @@ export declare const ApiAppConfigSchema: z.ZodObject<{
         scopes?: string[] | undefined;
     }> | undefined;
 }>;
+/**
+ * Type representing the validated API application configuration.
+ *
+ * This type is inferred from the Zod schema and should be used throughout the CLI
+ * to ensure type safety and consistency with the schema.
+ */
 export type ApiAppConfig = z.infer<typeof ApiAppConfigSchema>;

package/dist/types/lib/dev-server.d.ts

@@ -0,0 +1,2 @@
+export { loadDevServerConfig, defineDevServerConfig, type DevServerConfigFn, type DevServerConfigExport, } from './load-dev-server-config.js';
+export { mergeDevServerConfig } from './merge-dev-server-config.js';

package/dist/types/lib/framework.node.d.ts

@@ -0,0 +1,77 @@
+import { type ModulesInstance } from '@equinor/fusion-framework-module';
+import { type MsalNodeModule } from '@equinor/fusion-framework-module-msal-node';
+import { type HttpModule } from '@equinor/fusion-framework-module-http';
+import { type ServiceDiscoveryModule } from '@equinor/fusion-framework-module-service-discovery';
+type Modules = [MsalNodeModule, HttpModule, ServiceDiscoveryModule];
+/**
+ * Type representing the initialized Fusion Framework instance.
+ * This is a composition of the modules defined in the Modules tuple.
+ */
+export type FusionFramework = ModulesInstance<Modules>;
+/**
+ * Enum for supported Fusion environments.
+ * Used to select the correct environment for service discovery and authentication.
+ */
+export declare enum FusionEnv {
+    ContinuesIntegration = "ci",
+    QualityAssurance = "fqa",
+    Training = "tr",
+    Production = "fprd",
+    Development = "dev"
+}
+/**
+ * Resolves the default environment based on CI status and dev allowance.
+ *
+ * @param allowDev - If true, allows development environment when not in CI.
+ * @returns The resolved Fusion environment.
+ */
+export declare const resolveDefaultEnv: (allowDev: boolean) => FusionEnv.ContinuesIntegration | FusionEnv.Development;
+/**
+ * Auth option for direct token usage.
+ */
+interface AuthTokenOptions {
+    token: string;
+}
+/**
+ * Auth option for silent authentication (non-interactive).
+ */
+interface AuthSilentOptions {
+    clientId: string;
+    tenantId: string;
+    interactive?: false;
+}
+/**
+ * Auth option for interactive authentication, including server config.
+ */
+interface AuthInteractiveOptions extends Omit<AuthSilentOptions, 'interactive'> {
+    interactive: true;
+    server: {
+        port: number;
+        onOpen?: (url: string) => void;
+    };
+}
+/**
+ * Settings for initializing the Fusion Framework.
+ * Includes environment, authentication, and service discovery options.
+ */
+export type FusionFrameworkSettings = {
+    env?: (typeof FusionEnv)[keyof typeof FusionEnv];
+    auth: AuthTokenOptions | AuthSilentOptions | AuthInteractiveOptions;
+    serviceDiscovery?: {
+        url?: string;
+        scope?: string[];
+    };
+};
+/**
+ * Initializes the Fusion Framework with the provided settings.
+ *
+ * This function configures HTTP, service discovery, and authentication modules
+ * based on the supplied configuration. It supports multiple authentication modes
+ * and allows customization of service discovery endpoints and scopes.
+ *
+ * @param config - The settings for framework initialization.
+ * @returns A promise resolving to the initialized Fusion Framework instance.
+ * @throws Will throw if required authentication parameters are missing.
+ */
+export declare const initializeFramework: (config: FusionFrameworkSettings) => Promise<FusionFramework>;
+export {};

package/dist/types/lib/index.d.ts

@@ -1,3 +1,4 @@
-export { mergeManifests, defineAppManifest, type AppManifestFn } from './app-manifest.js';
-export { defineAppConfig, type AppConfigFn, type AppConfigExport } from './app-config.js';
-export { defineAppPackage, resolveAppKey, resolveEntryPoint, type AppPackageJson, type ResolvedAppPackage, } from './app-package.js';
+export type { RuntimeEnv } from './types.js';
+export type { ResolvedPackage } from './utils/resolve-package.js';
+export { initializeFramework, type FusionFramework } from './framework.node.js';
+export { defineAppConfig, defineAppManifest } from './legacy.js';

package/dist/types/lib/legacy.d.ts

@@ -0,0 +1,24 @@
+import { defineAppConfig as _defineConfig } from './app/app-config.js';
+import { defineAppManifest as _defineManifest } from './app/app-manifest.js';
+/**
+ * @deprecated
+ * Will be removed in the next major version.
+ * Please use `defineAppConfig` from `@equinor/fusion-framework-cli/app` instead.
+ *
+ * Transitional wrapper for legacy defineAppConfig. This function exists only to prevent immediate breaking changes
+ * and should be removed as soon as possible. Consumers should migrate to the new API without delay.
+ *
+ * @param args - Arguments passed to the new defineAppConfig function.
+ */
+export declare const defineAppConfig: (...args: Parameters<typeof _defineConfig>) => import("./app/app-config.js").AppConfigFn;
+/**
+ * @deprecated
+ * Will be removed in the next major version.
+ * Please use `defineAppManifest` from `@equinor/fusion-framework-cli/app` instead.
+ *
+ * Transitional wrapper for legacy defineAppManifest. This function exists only to prevent immediate breaking changes
+ * and should be removed as soon as possible. Consumers should migrate to the new API without delay.
+ *
+ * @param args - Arguments passed to the new defineAppManifest function.
+ */
+export declare const defineAppManifest: (...args: Parameters<typeof _defineManifest>) => import("./app/app-manifest.js").AppManifestFn<import("@equinor/fusion-framework-module-app").AppManifest>;

package/dist/types/lib/load-dev-server-config.d.ts

@@ -0,0 +1,40 @@
+import { type ImportConfigResult } from '@equinor/fusion-imports';
+import type { RuntimeEnv } from './types.js';
+import type { DevServerOptions } from '@equinor/fusion-framework-dev-server';
+/**
+ * Type definition for a function that generates or modifies DevServerOptions.
+ * @param env - The runtime environment configuration.
+ * @param args - An object containing the base DevServerOptions.
+ * @returns A DevServerOptions object or a Promise resolving to one, or undefined.
+ */
+export type DevServerConfigFn = (env: RuntimeEnv, args: {
+    base: DevServerOptions;
+}) => Promise<DevServerOptions | undefined> | DevServerOptions | undefined;
+/**
+ * Type definition for a dev server config export, which can be either a DevServerOptions object or a function.
+ */
+export type DevServerConfigExport = DevServerOptions | DevServerConfigFn;
+/**
+ * Helper to define a dev server config function with proper typing.
+ * @param fn - The configuration function to be used as the dev server config.
+ * @returns The same function, typed as DevServerConfigFn.
+ */
+export declare const defineDevServerConfig: (fn: DevServerConfigFn) => DevServerConfigFn;
+/**
+ * Loads the dev server configuration from a file or function.
+ *
+ * @param env - The runtime environment configuration.
+ * @param base - The base DevServerOptions to use as defaults.
+ * @param options - Optional settings for file name and extensions.
+ * @returns A promise resolving to the imported config result.
+ *
+ * This function uses importConfig to dynamically load the configuration file.
+ * If the config export is a function, it is invoked with the environment and a cloned base config.
+ * If the config export is an object, it is merged with the base config.
+ *
+ * Inline comments are provided for maintainability and clarity.
+ */
+export declare const loadDevServerConfig: (env: RuntimeEnv, base: DevServerOptions, options?: {
+    file?: string;
+    extensions?: string[];
+}) => Promise<ImportConfigResult<DevServerOptions>>;

package/dist/types/lib/merge-dev-server-config.d.ts

@@ -0,0 +1,16 @@
+import type { DevServerOptions } from '@equinor/fusion-framework-dev-server';
+import type { RecursivePartial } from './utils/types';
+/**
+ * Merges a base development server configuration with an overrides object.
+ *
+ * Uses lodash.mergeWith to deeply merge properties, with custom logic for arrays.
+ * Arrays in the overrides object will replace arrays in the base config.
+ *
+ * @param base - The base development server configuration.
+ * @param overrides - A partial configuration object containing properties to override in the base configuration.
+ * @returns The merged development server configuration.
+ *
+ * Inline comments are provided for maintainability and clarity.
+ */
+export declare const mergeDevServerConfig: (base: DevServerOptions, overrides: RecursivePartial<DevServerOptions>) => DevServerOptions;
+export default mergeDevServerConfig;

package/dist/types/lib/portal/create-portal-manifest.d.ts

@@ -0,0 +1,22 @@
+import type { PackageJson } from 'type-fest';
+import type { RuntimeEnv } from '../types';
+import type { PortalManifest } from './portal-manifest.js';
+/**
+ * Creates a `PortalManifest` object from the provided `package.json` data and runtime environment.
+ *
+ * This function validates the input package information, determines the appropriate entry point,
+ * extracts metadata such as the app key, version, and repository information, and constructs a manifest
+ * object suitable for use in portal deployment and development workflows.
+ *
+ * @param env - The runtime environment, containing information such as the current command (e.g., 'build', 'dev').
+ * @param packageJson - The parsed `package.json` object for the portal package, expected to include at least `name` and `version`.
+ * @returns A fully constructed `PortalManifest` object containing metadata, build information, and asset configuration.
+ *
+ * @throws Will throw an error if `packageJson` is not a valid object or is missing required fields.
+ *
+ * @remarks
+ * - Maintainers: This function is the canonical way to generate a portal manifest from package metadata.
+ * - The manifest structure is tightly coupled to the portal build and deployment pipeline.
+ * - If you add new fields to the manifest, update this function and its documentation accordingly.
+ */
+export declare const createPortalManifestFromPackage: (env: RuntimeEnv, packageJson: PackageJson) => PortalManifest;

package/dist/types/lib/portal/index.d.ts

@@ -0,0 +1,2 @@
+export { createPortalManifestFromPackage, definePortalManifest, loadPortalManifest, validatePortalManifest, type PortalManifest, type PortalManifestExport, type PortalManifestFn, } from './portal-manifest.js';
+export { loadPortalSchema, definePortalSchema, type PortalSchema, type PortalSchemaExport, type PortalSchemaFn, } from './load-portal-schema.js';

package/dist/types/lib/portal/load-portal-manifest.d.ts

@@ -0,0 +1,65 @@
+import type { RuntimeEnv } from '../types';
+import type { PortalManifest } from './portal-manifest.js';
+/**
+ * A function type for generating or modifying a portal manifest based on the runtime environment and provided arguments.
+ *
+ * @template T - A type extending a partial `PortalManifest`.
+ * @param env - The current runtime environment.
+ * @param args - An object containing a `base` property, which is a partial portal manifest of type `T`.
+ * @returns The resulting portal manifest of type `T`, a promise resolving to `T` or `void`, or `void`.
+ */
+export type PortalManifestFn<T extends Partial<PortalManifest>> = (env: RuntimeEnv, args: {
+    base: T;
+}) => T | Promise<T | void> | T | void;
+/**
+ * Represents a value that can either be a partial portal manifest object or a function returning such an object.
+ *
+ * @typeParam T - A type extending `Partial<PortalManifest>`, representing the shape of the portal manifest.
+ *
+ * This type is useful for scenarios where a portal manifest can be provided directly as an object,
+ * or as a function (possibly asynchronous or parameterized) that returns the manifest object.
+ */
+export type PortalManifestExport<T extends Partial<PortalManifest>> = T | PortalManifestFn<T>;
+/**
+ * Represents the result of loading a portal manifest file.
+ *
+ * @template T - A type extending `Partial<PortalManifest>`, representing the manifest's shape.
+ * @property manifest - The loaded manifest object.
+ * @property path - The file system path to the manifest file.
+ * @property extension - The file extension of the manifest file.
+ */
+type LoadAppManifestResult<T extends Partial<PortalManifest>> = {
+    manifest: T;
+    path: string;
+    extension: string;
+};
+/**
+ * Options for loading a portal manifest configuration file.
+ *
+ * @template T - The type of the portal manifest, extending Partial<PortalManifest>.
+ * @property base - An optional base manifest object to merge with the loaded configuration.
+ * @property file - A string or array of strings specifying possible manifest file names to load.
+ * @property extensions - An array of file extensions to consider when resolving the manifest file.
+ */
+export type LoadPortalManifestOptions<T extends Partial<PortalManifest>> = {
+    base?: T;
+    file?: string | string[];
+    extensions?: string[];
+};
+/**
+ * Loads a portal manifest configuration file, merging it with optional base values and supporting multiple file extensions.
+ *
+ * @template T - The type of the portal manifest, extending Partial<PortalManifest>. Defaults to PortalManifest.
+ * @param env - The runtime environment containing configuration such as the root directory and environment name.
+ * @param options - Optional settings for loading the manifest.
+ * @returns A promise that resolves to a `LoadAppManifestResult<T>` containing the loaded manifest, the file path, and the file extension.
+ *
+ * This function is the main entry point for loading portal manifest files. It supports merging with a base manifest, custom file name suggestions, and extension filtering.
+ *
+ * Example usage:
+ * ```ts
+ * const result = await loadPortalManifest(env, { base: {}, file: 'custom.manifest' });
+ * ```
+ */
+export declare const loadPortalManifest: <T extends Partial<PortalManifest> = PortalManifest>(env: RuntimeEnv, options?: LoadPortalManifestOptions<T>) => Promise<LoadAppManifestResult<T>>;
+export {};

package/dist/types/lib/portal/load-portal-schema.d.ts

@@ -0,0 +1,43 @@
+import type { RuntimeEnv } from '../types';
+/**
+ * Represents a generic portal schema as a record of key-value pairs.
+ */
+export type PortalSchema = Record<string, unknown>;
+/**
+ * A function that returns a portal schema, possibly asynchronously, based on the provided runtime environment.
+ * @template T - The type of the portal schema.
+ * @param env - The runtime environment used to generate the schema.
+ * @returns The portal schema or a promise resolving to the schema.
+ */
+export type PortalSchemaFn<T extends PortalSchema> = (env: RuntimeEnv) => T | Promise<T> | T;
+/**
+ * Represents either a portal schema object or a function that returns a portal schema.
+ * @template T - The type of the portal schema.
+ */
+export type PortalSchemaExport<T extends PortalSchema> = T | PortalSchemaFn<T>;
+/**
+ * Helper to define a portal schema function with type inference.
+ * @template T - The type of the portal schema.
+ * @param fn - The schema function to define.
+ * @returns The provided schema function.
+ */
+export declare const definePortalSchema: <T extends PortalSchema>(fn: PortalSchemaFn<T>) => PortalSchemaFn<T>;
+/**
+ * Loads a portal schema from configuration files or schema functions.
+ *
+ * @template T - The type of the portal schema.
+ * @param env - The runtime environment used to resolve the schema.
+ * @param options - Optional configuration for file names and extensions.
+ * @returns An object containing the loaded schema, file path, and extension.
+ *
+ * This function attempts to import a schema configuration file or function based on the provided environment and options.
+ * It supports both direct schema objects and schema factory functions. The schema is resolved and validated before returning.
+ */
+export declare const loadPortalSchema: <T extends PortalSchema>(env: RuntimeEnv, options?: {
+    file?: string | string[];
+    extensions?: string[];
+}) => Promise<{
+    schema: T;
+    path: string;
+    extension: string;
+}>;

package/dist/types/lib/portal/portal-manifest.d.ts

@@ -0,0 +1,16 @@
+import type { PortalManifestFn } from './load-portal-manifest.js';
+import type { PortalManifestSchemaType } from './portal-manifest.schema.js';
+export { loadPortalManifest, type PortalManifestExport, type PortalManifestFn, } from './load-portal-manifest.js';
+export { createPortalManifestFromPackage } from './create-portal-manifest.js';
+export declare const definePortalManifest: <T extends PortalManifestSchemaType>(fn: PortalManifestFn<T>) => PortalManifestFn<T>;
+export { PortalManifestSchema, PortalManifestBuildSchema, PortalManifestSchemaType as PortalManifest, type PortalManifestBuildSchemaType as PortalManifestBuild, } from './portal-manifest.schema.js';
+/**
+ * Validates a portal manifest object against the PortalManifestSchema.
+ *
+ * @param manifest - The manifest object to validate.
+ * @returns The validated manifest object (typed) if valid.
+ * @throws ZodError if validation fails.
+ *
+ * Use this utility to ensure a manifest conforms to the expected schema before further processing.
+ */
+export declare function validatePortalManifest(manifest: unknown): PortalManifestSchemaType;

package/dist/types/lib/portal/portal-manifest.schema.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Zod schema for validating the build section of the PortalManifest object.
+ *
+ * This schema defines the structure and types for the build metadata used in the portal manifest.
+ *
+ * @remarks
+ * - Maintainers: Update this schema if the build contract changes.
+ * - This schema is the canonical source for portal build validation and structure.
+ */
+import { z } from 'zod';
+export declare const PortalManifestBuildSchema: z.ZodObject<{
+    templateEntry: z.ZodString;
+    schemaEntry: z.ZodString;
+    assetPath: z.ZodOptional<z.ZodString>;
+    githubRepo: z.ZodOptional<z.ZodString>;
+    version: z.ZodString;
+    timestamp: z.ZodString;
+    commitSha: z.ZodString;
+    annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    projectPage: z.ZodOptional<z.ZodString>;
+    allowedExtensions: z.ZodArray<z.ZodString, "many">;
+    schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    timestamp: string;
+    commitSha: string;
+    allowedExtensions: string[];
+    templateEntry: string;
+    schemaEntry: string;
+    config?: Record<string, unknown> | undefined;
+    githubRepo?: string | undefined;
+    projectPage?: string | undefined;
+    assetPath?: string | undefined;
+    annotations?: Record<string, string> | undefined;
+    schema?: Record<string, unknown> | undefined;
+}, {
+    version: string;
+    timestamp: string;
+    commitSha: string;
+    allowedExtensions: string[];
+    templateEntry: string;
+    schemaEntry: string;
+    config?: Record<string, unknown> | undefined;
+    githubRepo?: string | undefined;
+    projectPage?: string | undefined;
+    assetPath?: string | undefined;
+    annotations?: Record<string, string> | undefined;
+    schema?: Record<string, unknown> | undefined;
+}>;
+/**
+ * Zod schema for validating the PortalManifest object.
+ *
+ * This schema defines the structure and types for the portal manifest used in the Fusion Framework CLI.
+ * It ensures that the manifest adheres to expected types and provides sensible defaults for build metadata.
+ *
+ * @remarks
+ * - Maintainers: Update this schema if the portal manifest contract changes.
+ * - This schema is the canonical source for portal manifest validation and structure.
+ */
+export declare const PortalManifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    build: z.ZodObject<{
+        templateEntry: z.ZodString;
+        schemaEntry: z.ZodString;
+        assetPath: z.ZodOptional<z.ZodString>;
+        githubRepo: z.ZodOptional<z.ZodString>;
+        version: z.ZodString;
+        timestamp: z.ZodString;
+        commitSha: z.ZodString;
+        annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        projectPage: z.ZodOptional<z.ZodString>;
+        allowedExtensions: z.ZodArray<z.ZodString, "many">;
+        schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        version: string;
+        timestamp: string;
+        commitSha: string;
+        allowedExtensions: string[];
+        templateEntry: string;
+        schemaEntry: string;
+        config?: Record<string, unknown> | undefined;
+        githubRepo?: string | undefined;
+        projectPage?: string | undefined;
+        assetPath?: string | undefined;
+        annotations?: Record<string, string> | undefined;
+        schema?: Record<string, unknown> | undefined;
+    }, {
+        version: string;
+        timestamp: string;
+        commitSha: string;
+        allowedExtensions: string[];
+        templateEntry: string;
+        schemaEntry: string;
+        config?: Record<string, unknown> | undefined;
+        githubRepo?: string | undefined;
+        projectPage?: string | undefined;
+        assetPath?: string | undefined;
+        annotations?: Record<string, string> | undefined;
+        schema?: Record<string, unknown> | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    build: {
+        version: string;
+        timestamp: string;
+        commitSha: string;
+        allowedExtensions: string[];
+        templateEntry: string;
+        schemaEntry: string;
+        config?: Record<string, unknown> | undefined;
+        githubRepo?: string | undefined;
+        projectPage?: string | undefined;
+        assetPath?: string | undefined;
+        annotations?: Record<string, string> | undefined;
+        schema?: Record<string, unknown> | undefined;
+    };
+    name: string;
+    displayName?: string | undefined;
+    description?: string | undefined;
+}, {
+    build: {
+        version: string;
+        timestamp: string;
+        commitSha: string;
+        allowedExtensions: string[];
+        templateEntry: string;
+        schemaEntry: string;
+        config?: Record<string, unknown> | undefined;
+        githubRepo?: string | undefined;
+        projectPage?: string | undefined;
+        assetPath?: string | undefined;
+        annotations?: Record<string, string> | undefined;
+        schema?: Record<string, unknown> | undefined;
+    };
+    name: string;
+    displayName?: string | undefined;
+    description?: string | undefined;
+}>;
+/**
+ * Type representing the validated PortalManifest configuration.
+ *
+ * This type is inferred from the Zod schema and should be used throughout the CLI
+ * to ensure type safety and consistency with the schema.
+ */
+export type PortalManifestSchemaType = z.infer<typeof PortalManifestSchema>;
+/**
+ * Type representing the validated build section of the PortalManifest.
+ *
+ * This type is inferred from the build Zod schema and should be used for build-specific logic.
+ */
+export type PortalManifestBuildSchemaType = z.infer<typeof PortalManifestBuildSchema>;

package/dist/types/lib/static.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A constant array of supported asset file extensions categorized by type.
+ *
+ * The extensions are grouped as follows:
+ * - **Images**: `png`, `jpg`, `jpeg`, `gif`, `svg`, `ico`, `webp`
+ * - **Videos and audio**: `mp4`, `webm`, `mp3`
+ * - **Fonts**: `woff2`, `woff`, `eot`, `ttf`, `otf`
+ * - **Documents**: `pdf`, `md`, `txt`
+ */
+export declare const ASSET_EXTENSIONS: readonly ["png", "jpg", "jpeg", "gif", "svg", "ico", "webp", "mp4", "webm", "mp3", "woff2", "woff", "eot", "ttf", "otf", "pdf", "md", "txt"];

package/dist/types/lib/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Represents the runtime environment configuration for CLI commands.
+ *
+ * This type is used to pass environment and context information to CLI utilities and configuration loaders.
+ *
+ * @property command - The CLI command being executed (e.g., 'serve' or 'build').
+ * @property mode - The CLI mode (e.g., development, production, etc.).
+ * @property root - The root directory of the package (optional).
+ * @property isPreview - Indicates if the CLI is running in preview mode (optional).
+ * @property environment - The runtime environment, such as 'local' or 'ci' (optional, can be null).
+ */
+export type RuntimeEnv = {
+    /**
+     * The CLI command being executed. Used to determine the operation mode for downstream logic.
+     * Example: 'serve' or 'build'.
+     */
+    command: 'serve' | 'build';
+    /**
+     * The CLI mode, typically used to distinguish between environments like development or production.
+     */
+    mode: string;
+    /**
+     * The root directory of the package. Used as a base path for resolving files and configs.
+     */
+    root?: string;
+    /**
+     * Indicates if the CLI is running in preview mode. Useful for toggling preview-specific logic.
+     */
+    isPreview?: boolean;
+    /**
+     * The runtime environment, such as 'local' or 'ci'. Allows for environment-specific configuration.
+     */
+    environment?: string | null;
+};

package/dist/types/lib/utils/assert.d.ts

@@ -1,8 +1,56 @@
 import assert, { AssertionError } from 'node:assert';
+/**
+ * Re-exports the core Node.js assert function and AssertionError class.
+ * Useful for consistent assertion handling throughout the codebase.
+ */
 export { assert, AssertionError };
+/**
+ * Asserts that the provided value is a valid number (not NaN).
+ * Throws an AssertionError if the value is not a number.
+ *
+ * @param value - The value to check for being a number.
+ * @param message - Optional custom error message for assertion failure.
+ * @throws {AssertionError} If value is NaN.
+ */
 export declare function assertNumber(value: unknown, message?: string): asserts value;
+/**
+ * Asserts that a file exists at the given path.
+ * Throws an error if the file does not exist.
+ *
+ * @param value - The file path to check.
+ * @param message - Optional custom error message for assertion failure.
+ * @throws {AssertionError} If the file does not exist.
+ */
+export declare const assertFileExists: (value: unknown, message?: string) => asserts value;
+/**
+ * Asserts that the provided value is an object.
+ * Throws an error if the value is not an object.
+ *
+ * @param value - The value to check for being an object.
+ * @param message - Optional custom error message or Error instance.
+ * @throws {AssertionError} If value is not an object.
+ */
 export declare function assertObject(value: object, message?: string | Error): asserts value;
+/**
+ * Asserts that a specific property exists and has a value on an object.
+ * Used internally for property value checks.
+ *
+ * @param value - The value of the property to check.
+ * @param prop - The property key being checked.
+ * @param message - Optional custom error message.
+ * @throws {AssertionError} If the property value is falsy.
+ */
 declare function assertObjectEntryValue<P>(value: unknown, prop: P, message?: string): asserts value;
+/**
+ * Asserts that an object contains the specified properties and that each property has a value.
+ * Allows for custom assertion logic and pre-message prefixing.
+ *
+ * @typeParam T - The object type to check.
+ * @typeParam P - The array of property keys to check on the object.
+ * @param value - The object to check.
+ * @param options - Optional settings for property keys, assertion function, and message prefix.
+ * @throws {AssertionError} If any property is missing or fails the assertion.
+ */
 export declare function assertObjectEntries<T extends object, P extends Array<keyof T>>(value: T, options?: {
     props?: P;
     assertion?: typeof assertObjectEntryValue;

package/dist/types/lib/utils/index.d.ts

@@ -0,0 +1,5 @@
+export { resolveEntryPoint } from './resolve-source-entry-point.js';
+export { resolvePackage, type ResolvedPackage } from './resolve-package.js';
+export { fileExists, fileExistsSync } from './file-exists.js';
+export { writeFile } from './write-file.js';
+export { resolveAnnotations } from './resolve-annotations.js';

package/dist/types/lib/utils/resolve-annotations.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resolves CI/CD environment-specific annotation variables.
+ *
+ * This function determines the current CI/CD runtime environment (GitHub Actions, Azure DevOps, or other)
+ * and returns a set of annotation variables relevant to that environment. These annotations are typically
+ * used for reporting build, test, or deployment results in a way that is compatible with the CI/CD provider's UI.
+ *
+ * @returns {Record<string, string>} An object containing annotation variables for the detected environment.
+ * If no known environment is detected, returns an empty object.
+ */
+export declare const resolveAnnotations: () => Record<string, string>;

package/dist/types/lib/utils/resolve-devops-annotations.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Resolves Azure DevOps-specific annotation variables from environment variables.
+ *
+ * This function extracts relevant build and repository information from Azure DevOps environment variables.
+ * It constructs a set of annotation variables that can be used for reporting or logging purposes in CI/CD pipelines.
+ *
+ * @returns {Record<string, string>} An object containing Azure DevOps annotation variables such as runId, repository,
+ * project, orgUrl, actor, branch, commitId, and runUrl. If a variable is not found, its value defaults to 'unknown'.
+ *
+ * Environment variables used by this function (see: https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-pipelines&tabs=yaml):
+ *   - BUILD_BUILDID: Unique build/run identifier
+ *   - BUILD_REPOSITORY_NAME: Repository name
+ *   - SYSTEM_TEAMPROJECT: Project name
+ *   - SYSTEM_COLLECTIONURI: Organization URL
+ *   - BUILD_REQUESTEDFOR: User who requested the build
+ *   - BUILD_SOURCEBRANCH: Source branch name
+ *   - BUILD_SOURCEVERSION: Commit SHA
+ *
+ * Notes for maintainers:
+ *   - If any environment variable is missing, its value defaults to 'unknown'.
+ *   - The runUrl is constructed only if orgUrl, project, and runId are available; otherwise, it is set to 'unknown'.
+ *   - If you need additional Azure DevOps context, refer to the official documentation and add new variables here.
+ *   - Some variables may contain sensitive information. Use caution when logging or exposing these values.
+ *
+ * Extending this function:
+ *   - To add more annotations, extract additional environment variables as needed and include them in the returned object.
+ *   - For custom pipelines or self-hosted agents, verify that all required environment variables are available.
+ */
+export declare const resolveAnnotations: () => Record<string, string>;
+export default resolveAnnotations;