@nu-art/build-and-install 0.400.14 → 0.401.1

package/BuildAndInstall.d.ts

@@ -0,0 +1,40 @@
+import { Logger } from '@nu-art/ts-common';
+import { BaiParams } from './core/params.js';
+import { Phase } from './phases/definitions/index.js';
+import { UnitsMapper } from './units/discovery/UnitsMapper.js';
+import { ProjectUnit } from './units/base/ProjectUnit.js';
+import { PhaseManager } from './phases/PhaseManager.js';
+import { Unit_NodeProject } from './units/index.js';
+import { Workspace } from './workspace/Workspace.js';
+import { BaseCliParam } from '@nu-art/commando/cli-params/types';
+import { RunningStatusHandler } from './runtime/RunningStatusHandler.js';
+export declare const DefaultPhases: Phase<string>[][];
+type BAI_Options = {
+    pathToProject: string;
+    runtimeParams: BaseCliParam<string, any>[];
+};
+export declare class BuildAndInstall extends Logger {
+    private unitsMapper;
+    private phases;
+    private pathToProject;
+    readonly workspace: Workspace;
+    readonly nodeProjectUnit: Unit_NodeProject;
+    readonly runtimeParams: BaiParams;
+    readonly runningStatus: RunningStatusHandler;
+    readonly phaseManager: PhaseManager;
+    private _init;
+    constructor(config?: Partial<BAI_Options>);
+    init(): Promise<void>;
+    prepareUnitsMapper(unitsMapper: UnitsMapper): void;
+    setApplicativeUnits(projectUnits: ProjectUnit[]): void;
+    setPhases(phases: Phase<string>[][]): void;
+    /**
+     * @deprecated Use workspace.projectUnits instead
+     * Backward compatibility getter for existing tests
+     */
+    get projectUnits(): ReadonlyArray<ProjectUnit>;
+    run(): Promise<void>;
+    build(): Promise<void>;
+    private loadVersion;
+}
+export {};

package/BuildAndInstall.js

@@ -0,0 +1,155 @@
+import { BeLogged, DebugFlag, filterDuplicates, ImplementationMissingException, LogClient_Terminal, Logger, LogLevel, merge } from '@nu-art/ts-common';
+import { AllBaiParams } from './core/params.js';
+import { phases_Build, phases_Deploy, phases_Launch, phases_Terminating } from './phases/definitions/index.js';
+import { UnitsMapper } from './units/discovery/UnitsMapper.js';
+import { FilesCache } from './core/FilesCache.js';
+import { ProjectUnit } from './units/base/ProjectUnit.js';
+import { PhaseManager } from './phases/PhaseManager.js';
+import { Workspace } from './workspace/Workspace.js';
+import { resolve } from 'path';
+import { CONST_BaiConfig, CONST_NodeModules, CONST_VersionApp } from './config/consts.js';
+import { UnitMapper_FirebaseFunction, UnitMapper_FirebaseHosting, UnitMapper_NodeLib, UnitMapper_NodeProject } from './units/discovery/resolvers/index.js';
+import { CLIParamsResolver } from '@nu-art/commando/cli-params/CLIParamsResolver';
+import { RunningStatusHandler } from './runtime/RunningStatusHandler.js';
+import { FileSystemUtils } from '@nu-art/ts-common/utils/FileSystemUtils';
+export const DefaultPhases = [
+    ...phases_Build,
+    ...phases_Terminating,
+    ...phases_Launch,
+    ...phases_Deploy,
+];
+export class BuildAndInstall extends Logger {
+    unitsMapper;
+    phases = DefaultPhases;
+    pathToProject;
+    workspace;
+    nodeProjectUnit;
+    runtimeParams;
+    runningStatus;
+    phaseManager;
+    _init = false;
+    constructor(config = {}) {
+        super();
+        const defaultConfig = merge({
+            pathToProject: process.env.INIT_CWD ?? process.cwd(),
+        }, config);
+        defaultConfig.runtimeParams = filterDuplicates([...(config.runtimeParams ?? []), ...AllBaiParams], param => param.keyName);
+        this.runtimeParams = CLIParamsResolver.create(...defaultConfig.runtimeParams).resolveParamValue();
+        BeLogged.addClient(LogClient_Terminal);
+        this.pathToProject = defaultConfig.pathToProject;
+        this.runningStatus = new RunningStatusHandler(this.pathToProject, this.runtimeParams);
+        this.workspace = new Workspace();
+    }
+    async init() {
+        if (this._init)
+            return;
+        this._init = true;
+        await this.runningStatus.init();
+        if (this.runtimeParams.debug)
+            DebugFlag.DefaultLogLevel = LogLevel.Debug;
+        if (this.runtimeParams.verbose)
+            DebugFlag.DefaultLogLevel = LogLevel.Verbose;
+        this.workspace.setMinLevel(DebugFlag.DefaultLogLevel);
+        this.setMinLevel(DebugFlag.DefaultLogLevel);
+        this.logDebug('Runtime params:', this.runtimeParams);
+        this.unitsMapper = new UnitsMapper();
+        this.prepareUnitsMapper(this.unitsMapper);
+    }
+    prepareUnitsMapper(unitsMapper) {
+        unitsMapper
+            .addRules(UnitMapper_NodeLib)
+            .addRules(UnitMapper_NodeProject)
+            .addRules(UnitMapper_FirebaseHosting)
+            .addRules(UnitMapper_FirebaseFunction)
+            .setRuntimeParams(this.runtimeParams);
+    }
+    setApplicativeUnits(projectUnits) {
+        this.workspace.addProjectUnits(projectUnits);
+    }
+    setPhases(phases) {
+        this.phases = phases;
+    }
+    /**
+     * @deprecated Use workspace.projectUnits instead
+     * Backward compatibility getter for existing tests
+     */
+    get projectUnits() {
+        return this.workspace.projectUnits;
+    }
+    async run() {
+        const executionPlan = await this.phaseManager.calculateExecutionSteps();
+        let killCounter = 0;
+        process.on('SIGINT', async () => {
+            this.logWarning('\n\n\n---------------------------------- Process Interrupted ----------------------------------\n\n\n');
+            await this.phaseManager.break();
+            killCounter++;
+            if (killCounter > 5)
+                process.exit(1);
+        });
+        try {
+            await this.phaseManager.execute(executionPlan);
+            this.logInfo('Completed successfully');
+            this.logInfo('---------------------------------- Process Completed successfully ----------------------------------');
+        }
+        catch (e) {
+            this.logInfo('Process Failed');
+            this.logInfo('---------------------------------- Process Failed ----------------------------------');
+            throw e;
+        }
+    }
+    async build() {
+        await this.init();
+        // Scan units from workspace
+        await this.workspace.scanUnits(this.pathToProject, this.unitsMapper);
+        const nodeProjectUnit = this.workspace.getNodeProjectUnit();
+        if (!nodeProjectUnit)
+            throw new ImplementationMissingException('NodeProject unit not found. Make sure you have a Unit_NodeProject in your project.');
+        // @ts-ignore
+        this['nodeProjectUnit'] = nodeProjectUnit;
+        const pathToBaiConfig = resolve(nodeProjectUnit.config.fullPath, CONST_BaiConfig);
+        this.logDebug(`Loading BAI-Config from: ${pathToBaiConfig}`);
+        const baiConfig = await FilesCache.load.json(pathToBaiConfig);
+        this.logVerbose('Loaded BAI-Config', baiConfig);
+        const globalOutputFolder = resolve(this.pathToProject, '.trash/output');
+        this.workspace.initializeDependencyMapper(globalOutputFolder);
+        let version = await this.loadVersion();
+        if (!(await FileSystemUtils.file.exists(resolve(nodeProjectUnit.config.fullPath, CONST_NodeModules)))) {
+            this.logInfo(`root project is missing ${CONST_NodeModules} folder. Enabling install...`);
+            this.runtimeParams.install = true;
+        }
+        // Derive active and project units based on runtime params
+        const units = this.workspace.deriveActiveAndProjectUnits(this.runtimeParams);
+        const childProjectUnits = this.workspace.getUnitsByKeys(units.projectUnits, ProjectUnit);
+        nodeProjectUnit.assignUnit(childProjectUnits);
+        this.logDebug(`Parent unit: ${nodeProjectUnit.config.key}`);
+        const runtimeContext = ({
+            version: version.version,
+            parentUnit: nodeProjectUnit,
+            childUnits: childProjectUnits,
+            baiConfig,
+            runtimeParams: this.runtimeParams,
+            unitsMapper: this.workspace.getDependencyMapper(),
+            unitsResolver: (keys, className) => {
+                return this.workspace.getUnitsByKeys(keys, className);
+            },
+            globalOutputFolder,
+            workspace: this.workspace,
+        });
+        this.workspace.projectUnits.forEach(unit => unit.setupRuntimeContext(runtimeContext));
+        const unitDependencyTree = await this.workspace.buildDependencyTree(units.projectUnits);
+        const manager = new PhaseManager(this.runningStatus, this.phases, unitDependencyTree, units.activeUnits, units.projectUnits);
+        // @ts-ignore
+        this['phaseManager'] = manager;
+    }
+    async loadVersion() {
+        const versionFilePath = resolve(this.pathToProject, CONST_VersionApp);
+        if (await FileSystemUtils.file.exists(versionFilePath)) {
+            this.logDebug('Loading version from: ', versionFilePath);
+            return await FileSystemUtils.file.read.json(versionFilePath, { version: '1.0.0' });
+        }
+        else {
+            this.logWarning(`No version file found at '${versionFilePath}', using default version: '1.0.0'`);
+            return { version: '1.0.0' };
+        }
+    }
+}

package/build-and-install-v3.d.ts

@@ -1,32 +1 @@
-import { Logger } from '@nu-art/ts-common';
-import { BaiParams } from './core/params/params.js';
-import { Phase } from './v3/phase/index.js';
-import { UnitsMapper } from './v3/UnitsMapper/UnitsMapper.js';
-import { ProjectUnit } from './v3/units/ProjectUnit.js';
-import { Unit_NodeProject } from './v3/units/index.js';
-import { BaseCliParam } from '@nu-art/commando/cli-params/types';
-import { RunningStatusHandler } from './v3/RunningStatusHandler.js';
-export declare const DefaultPhases: Phase<string>[][];
-type BAI_Options = {
-    pathToProject: string;
-    runtimeParams: BaseCliParam<string, any>[];
-};
-export declare class BuildAndInstall extends Logger {
-    private unitsMapper;
-    private phases;
-    private pathToProject;
-    private allUnits;
-    readonly nodeProjectUnit: Unit_NodeProject;
-    readonly runtimeParams: BaiParams;
-    readonly projectUnits: ProjectUnit[];
-    private unitsDependencyMapper;
-    readonly runningStatus: RunningStatusHandler;
-    constructor(config?: Partial<BAI_Options>);
-    init(): Promise<void>;
-    prepareUnitsMapper(unitsMapper: UnitsMapper): void;
-    setApplicativeUnits(projectUnits: ProjectUnit[]): void;
-    setPhases(phases: Phase<string>[][]): void;
-    build(): Promise<ProjectUnit<import("./v3/units/ProjectUnit.js").Config_ProjectUnit>[]>;
-    run(): Promise<void>;
-}
-export {};
+export * from './BuildAndInstall.js';

package/build-and-install-v3.js

@@ -1,154 +1 @@
-import { _keys, arrayToMap, BeLogged, DebugFlag, filterDuplicates, ImplementationMissingException, LogClient_Terminal, Logger, LogLevel, merge } from '@nu-art/ts-common';
-import { AllBaiParams } from './core/params/params.js';
-import { phases_Build, phases_Deploy, phases_Launch, phases_Terminating } from './v3/phase/index.js';
-import { UnitsMapper } from './v3/UnitsMapper/UnitsMapper.js';
-import { UnitsDependencyMapper } from './v3/UnitsDependencyMapper/UnitsDependencyMapper.js';
-import { FilesCache } from './v3/core/FilesCache.js';
-import { ProjectUnit } from './v3/units/ProjectUnit.js';
-import { PhaseManager } from './v3/PhaseManager.js';
-import { Unit_NodeProject } from './v3/units/index.js';
-import { resolve } from 'path';
-import { CONST_BaiConfig, CONST_NodeModules, CONST_VersionApp } from './core/consts.js';
-import { UnitMapper_FirebaseFunction, UnitMapper_FirebaseHosting, UnitMapper_NodeLib, UnitMapper_NodeProject } from './v3/UnitsMapper/resolvers/index.js';
-import { CLIParamsResolver } from '@nu-art/commando/cli-params/CLIParamsResolver';
-import { RunningStatusHandler } from './v3/RunningStatusHandler.js';
-import { FileSystemUtils } from '@nu-art/ts-common/utils/FileSystemUtils';
-export const DefaultPhases = [
-    ...phases_Build,
-    ...phases_Terminating,
-    ...phases_Launch,
-    ...phases_Deploy,
-];
-export class BuildAndInstall extends Logger {
-    unitsMapper;
-    phases = DefaultPhases;
-    pathToProject;
-    allUnits = [];
-    nodeProjectUnit;
-    runtimeParams;
-    projectUnits = [];
-    unitsDependencyMapper;
-    runningStatus;
-    constructor(config = {}) {
-        super();
-        const defaultConfig = merge({
-            pathToProject: process.env.INIT_CWD ?? process.cwd(),
-        }, config);
-        defaultConfig.runtimeParams = filterDuplicates([...(config.runtimeParams ?? []), ...AllBaiParams], param => param.keyName);
-        this.runtimeParams = CLIParamsResolver.create(...defaultConfig.runtimeParams).resolveParamValue();
-        BeLogged.addClient(LogClient_Terminal);
-        this.pathToProject = defaultConfig.pathToProject;
-        this.runningStatus = new RunningStatusHandler(this.pathToProject, this.runtimeParams);
-    }
-    async init() {
-        await this.runningStatus.init();
-        if (this.runtimeParams.debug)
-            DebugFlag.DefaultLogLevel = LogLevel.Debug;
-        if (this.runtimeParams.verbose)
-            DebugFlag.DefaultLogLevel = LogLevel.Verbose;
-        this.setMinLevel(DebugFlag.DefaultLogLevel);
-        this.logDebug('Runtime params:', this.runtimeParams);
-        this.unitsMapper = new UnitsMapper();
-        this.prepareUnitsMapper(this.unitsMapper);
-    }
-    prepareUnitsMapper(unitsMapper) {
-        unitsMapper
-            .addRules(UnitMapper_NodeLib)
-            .addRules(UnitMapper_NodeProject)
-            .addRules(UnitMapper_FirebaseHosting)
-            .addRules(UnitMapper_FirebaseFunction)
-            .setRuntimeParams(this.runtimeParams);
-    }
-    setApplicativeUnits(projectUnits) {
-        this.projectUnits.push(...projectUnits);
-    }
-    setPhases(phases) {
-        this.phases = phases;
-    }
-    async build() {
-        await this.init();
-        this.logVerbose(`Resolving units from: ${this.pathToProject}`);
-        this.allUnits = await this.unitsMapper.resolveUnits(this.pathToProject);
-        Object.freeze(this.allUnits);
-        this.logDebug('Units found:', this.allUnits.map(unit => `${unit.constructor?.['name']}: ${unit.config.key}`).join('\n'));
-        const unitKeyToUnitMap = arrayToMap(this.allUnits, unit => unit.config.key);
-        const allProjectUnits = this.allUnits.filter(unit => unit.isInstanceOf(ProjectUnit));
-        const nodeProjectUnit = allProjectUnits.find(unit => unit.isInstanceOf(Unit_NodeProject));
-        // @ts-ignore
-        this['nodeProjectUnit'] = nodeProjectUnit;
-        if (!this.nodeProjectUnit)
-            throw new ImplementationMissingException('NodeProject unit not found. Make sure you have a Unit_NodeProject in your project.');
-        this.nodeProjectUnit.assignUnit(allProjectUnits);
-        this.logDebug(`Parent unit: ${this.nodeProjectUnit.config.key}`);
-        this.logDebug(`Child units: ${allProjectUnits.map(unit => unit.config.key).join(', ')}`);
-        const pathToBaiConfig = resolve(this.nodeProjectUnit.config.fullPath, CONST_BaiConfig);
-        this.logVerbose(`Loading BAI-Config from: ${pathToBaiConfig}`);
-        const baiConfig = await FilesCache.load.json(pathToBaiConfig);
-        this.logDebug('Loaded BAI-Config', baiConfig);
-        this.projectUnits.push(...allProjectUnits);
-        Object.freeze(this.projectUnits);
-        const unitsDependencies = this.projectUnits.map(unit => ({
-            key: unit.config.key,
-            dependsOn: _keys(unit.config.dependencies).filter(key => !!unitKeyToUnitMap[key])
-        }));
-        const globalOutputFolder = resolve(this.pathToProject, '.trash/output');
-        this.unitsDependencyMapper = new UnitsDependencyMapper(unitsDependencies, globalOutputFolder);
-        const versionFilePath = resolve(this.pathToProject, CONST_VersionApp);
-        this.logInfo('loading version from: ', versionFilePath);
-        const version = await FileSystemUtils.file.read.json(versionFilePath, { version: '1.0.0' });
-        const runtimeContext = ({
-            version: version.version,
-            parentUnit: this.nodeProjectUnit,
-            childUnits: allProjectUnits,
-            baiConfig,
-            runtimeParams: this.runtimeParams,
-            unitsMapper: this.unitsDependencyMapper,
-            unitsResolver: (keys, className) => {
-                return keys.map(key => unitKeyToUnitMap[key]).filter(unit => unit.isInstanceOf(className));
-            },
-            globalOutputFolder,
-        });
-        this.projectUnits.forEach(unit => unit.setupRuntimeContext(runtimeContext));
-        if (!(await FileSystemUtils.file.exists(resolve(this.nodeProjectUnit.config.fullPath, CONST_NodeModules)))) {
-            this.logInfo(`root project is missing ${CONST_NodeModules} folder. Enabling install...`);
-            this.runtimeParams.install = true;
-        }
-        return allProjectUnits;
-    }
-    async run() {
-        const keyToUnitMap = arrayToMap(this.projectUnits, u => u.config.key);
-        let topLevelAppKeys = this.projectUnits.filter(unit => unit.config.isTopLevelApp).map(unit => unit.config.key);
-        this.logWarning('this.runtimeParams.includeApps', this.runtimeParams.includeApps);
-        if (this.runtimeParams.includeApps?.length) {
-            this.logWarning('HEREHREHREHRHERHER');
-            const regexMatchers = this.runtimeParams.includeApps.map(filter => new RegExp(`.*?${filter}.*?`, 'i'));
-            topLevelAppKeys = topLevelAppKeys.filter(unitKey => regexMatchers.some(matcher => matcher.test(unitKey)));
-        }
-        this.logDebug('topLevelAppKeys: ', topLevelAppKeys);
-        const participatingUnitKeys = this.runtimeParams.allUnits
-            ? undefined
-            : [...this.unitsDependencyMapper.getTransitiveDependencies(topLevelAppKeys), ...topLevelAppKeys];
-        const unitDependencyTree = (await this.unitsDependencyMapper.buildDependencyTree(participatingUnitKeys))
-            .map(units => units.map(unitKey => keyToUnitMap[unitKey]));
-        const phaseManager = new PhaseManager(this.runningStatus, this.phases, unitDependencyTree);
-        const executionPlan = await phaseManager.calculateExecutionSteps();
-        let killCounter = 0;
-        process.on('SIGINT', async () => {
-            this.logWarning('\n\n\n---------------------------------- Process Interrupted ----------------------------------\n\n\n');
-            await phaseManager.break();
-            killCounter++;
-            if (killCounter > 5)
-                process.exit(1);
-        });
-        try {
-            await phaseManager.execute(executionPlan);
-            this.logInfo('Completed successfully');
-            this.logInfo('---------------------------------- Process Completed successfully ----------------------------------');
-        }
-        catch (e) {
-            this.logInfo('Process Failed');
-            this.logInfo('---------------------------------- Process Failed ----------------------------------');
-            throw e;
-        }
-    }
-}
+export * from './BuildAndInstall.js';

package/build-and-install.js

@@ -1,17 +1,17 @@
-import { BuildAndInstall } from './build-and-install-v3.js';
+/**
+ * Main entry point for build-and-install CLI.
+ *
+ * Creates a BuildAndInstall instance, builds the workspace, and executes all phases.
+ * Exits with code 0 on success, or logs errors and exits with code 0 (should probably exit with 1 on error).
+ */
+import { BuildAndInstall } from './BuildAndInstall.js';
 (async () => {
     const buildAndInstall = new BuildAndInstall();
     await buildAndInstall.build();
     await buildAndInstall.run();
 })()
-    .catch(console.error)
+    .catch((err) => {
+    console.error(err);
+    process.exit(2);
+})
     .then(() => process.exit(0));
-// .execute()
-// 	.then(() => {
-// 	})
-// 	.catch(err => {
-// 		process.on('SIGINT', () => {
-// 			console.log('Failed with error: ', err);
-// 			return process.exit(1);
-// 		});
-// 	});

package/config/consts.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Constants for file names and configuration keys used throughout the build system.
+ */
+import { MemKey } from '@nu-art/ts-common/mem-storage/index';
+import { RuntimeProjectConfig } from './types/index.js';
+/** Version file name (version-app.json) */
+export declare const CONST_VersionApp = "version-app.json";
+/** Package.json template file name (__package.json) */
+export declare const CONST_PackageJSONTemplate = "__package.json";
+/** Package.json file name */
+export declare const CONST_PackageJSON = "package.json";
+/** Node modules folder name */
+export declare const CONST_NodeModules = "node_modules";
+/** BAI configuration file name (bai-config.json) */
+export declare const CONST_BaiConfig = "bai-config.json";
+/** Firebase RC file name (.firebaserc) */
+export declare const CONST_FirebaseRC = ".firebaserc";
+/** Firebase JSON configuration file name (firebase.json) */
+export declare const CONST_FirebaseJSON = "firebase.json";
+/** TypeScript configuration file name (tsconfig.json) */
+export declare const CONST_TS_CONFIG = "tsconfig.json";
+/** PNPM workspace file name (pnpm-workspace.yaml) */
+export declare const CONST_PNPM_WORKSPACE = "pnpm-workspace.yaml";
+/** PNPM lock file name (pnpm-lock.yaml) */
+export declare const CONST_PNPM_LOCK = "pnpm-lock.yaml";
+/** Trash directory name (.trash) */
+export declare const CONST_TrashDir = ".trash";
+/** Deployment metadata file name (deployment-metadata.json) */
+export declare const CONST_DeploymentMetadata = "deployment-metadata.json";
+/** Deployment ID metadata key (deployment-id) */
+export declare const CONST_DeploymentId = "deployment-id";
+/** Default version tag (latest) */
+export declare const CONST_LatestTag = "latest";
+/** Hosting build tarball name (hosting-build.tar.gz) */
+export declare const CONST_HostingBuildTarball = "hosting-build.tar.gz";
+/** Staging directory name (staging) */
+export declare const CONST_StagingDir = "staging";
+/** Deploy hosting temp directory name (deploy-hosting) */
+export declare const CONST_DeployHostingDir = "deploy-hosting";
+/** Build image temp directory name (build-image) */
+export declare const CONST_BuildImageDir = "build-image";
+/** Memory storage key for packages configuration */
+export declare const MemKey_Packages: MemKey<RuntimeProjectConfig>;

package/config/consts.js

@@ -0,0 +1,42 @@
+/**
+ * Constants for file names and configuration keys used throughout the build system.
+ */
+import { MemKey } from '@nu-art/ts-common/mem-storage/index';
+/** Version file name (version-app.json) */
+export const CONST_VersionApp = 'version-app.json';
+/** Package.json template file name (__package.json) */
+export const CONST_PackageJSONTemplate = '__package.json';
+/** Package.json file name */
+export const CONST_PackageJSON = 'package.json';
+/** Node modules folder name */
+export const CONST_NodeModules = 'node_modules';
+/** BAI configuration file name (bai-config.json) */
+export const CONST_BaiConfig = 'bai-config.json';
+/** Firebase RC file name (.firebaserc) */
+export const CONST_FirebaseRC = '.firebaserc';
+/** Firebase JSON configuration file name (firebase.json) */
+export const CONST_FirebaseJSON = 'firebase.json';
+/** TypeScript configuration file name (tsconfig.json) */
+export const CONST_TS_CONFIG = 'tsconfig.json';
+/** PNPM workspace file name (pnpm-workspace.yaml) */
+export const CONST_PNPM_WORKSPACE = 'pnpm-workspace.yaml';
+/** PNPM lock file name (pnpm-lock.yaml) */
+export const CONST_PNPM_LOCK = 'pnpm-lock.yaml';
+/** Trash directory name (.trash) */
+export const CONST_TrashDir = '.trash';
+/** Deployment metadata file name (deployment-metadata.json) */
+export const CONST_DeploymentMetadata = 'deployment-metadata.json';
+/** Deployment ID metadata key (deployment-id) */
+export const CONST_DeploymentId = 'deployment-id';
+/** Default version tag (latest) */
+export const CONST_LatestTag = 'latest';
+/** Hosting build tarball name (hosting-build.tar.gz) */
+export const CONST_HostingBuildTarball = 'hosting-build.tar.gz';
+/** Staging directory name (staging) */
+export const CONST_StagingDir = 'staging';
+/** Deploy hosting temp directory name (deploy-hosting) */
+export const CONST_DeployHostingDir = 'deploy-hosting';
+/** Build image temp directory name (build-image) */
+export const CONST_BuildImageDir = 'build-image';
+/** Memory storage key for packages configuration */
+export const MemKey_Packages = new MemKey('bai-packages', true);

package/{core → config}/package/consts.d.ts

@@ -1,6 +1,6 @@
 import { FirebasePackageConfig } from '../types/index.js';
 export type DefaultType_ProjectEnvs = 'local' | 'dev' | 'staging' | 'prod';
-export declare const Default_ProjectEnvs: ("local" | "dev" | "staging" | "prod")[];
+export declare const Default_ProjectEnvs: ("local" | "staging" | "dev" | "prod")[];
 export declare const Default_FunctionsIgnoreFiles: string[];
 export declare const Default_HostingConfig: {
     public: string;

package/{core → config}/types/project-config.d.ts

@@ -20,6 +20,9 @@ export type BAI_Config = {
         packageJson?: TypedMap<string>;
     };
     files?: {
+        docker?: {
+            dockerfile?: string;
+        };
         tests?: {
             firebase?: {
                 'firebase.json'?: string;

package/core/FilesCache.d.ts

@@ -0,0 +1,50 @@
+/**
+ * File cache for loading and caching file contents.
+ *
+ * **Purpose**: Avoids re-reading files multiple times during build process.
+ *
+ * **Caching Strategy**:
+ * - Files are cached in memory after first read
+ * - JSON files are parsed and frozen (immutable)
+ * - Text files are cached as strings
+ * - Cache persists for entire build session
+ *
+ * **Usage**: Used to load config files (bai-config.json, package.json, etc.)
+ * that are read multiple times during workspace scanning and unit initialization.
+ *
+ * **Clear Cache**: Call `FilesCache.clear()` to reset cache (useful for tests).
+ */
+export declare const FilesCache: {
+    /**
+     * Clears the file cache.
+     *
+     * Useful for tests or when files may have changed.
+     */
+    clear: () => {};
+    load: {
+        /**
+         * Loads and caches a JSON file.
+         *
+         * **Behavior**:
+         * - Returns cached value if already loaded
+         * - Parses JSON and freezes result (immutable)
+         * - Throws `ImplementationMissingException` if file doesn't exist or is not a file
+         *
+         * @param pathToFile - Path to JSON file
+         * @returns Promise resolving to parsed and frozen JSON object
+         */
+        json: <T>(pathToFile: string) => Promise<T>;
+        /**
+         * Loads and caches a text file.
+         *
+         * **Behavior**:
+         * - Returns cached value if already loaded
+         * - Reads file as UTF-8 text
+         * - Throws `ImplementationMissingException` if file doesn't exist or is not a file
+         *
+         * @param pathToFile - Path to text file
+         * @returns Promise resolving to file content as string
+         */
+        text: (pathToFile: string) => Promise<string>;
+    };
+};

package/core/FilesCache.js

@@ -0,0 +1,76 @@
+import { ImplementationMissingException } from '@nu-art/ts-common';
+import { promises as fs } from 'fs';
+let cachedFiles = {};
+const readFile = async (path) => {
+    try {
+        const fileStat = await fs.stat(path);
+        if (fileStat.isFile())
+            return await fs.readFile(path, 'utf-8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw new ImplementationMissingException(`file does not exist: ${path}`);
+        throw error; // rethrow other errors
+    }
+    throw new ImplementationMissingException(`expected a file at: ${path}`);
+};
+/**
+ * File cache for loading and caching file contents.
+ *
+ * **Purpose**: Avoids re-reading files multiple times during build process.
+ *
+ * **Caching Strategy**:
+ * - Files are cached in memory after first read
+ * - JSON files are parsed and frozen (immutable)
+ * - Text files are cached as strings
+ * - Cache persists for entire build session
+ *
+ * **Usage**: Used to load config files (bai-config.json, package.json, etc.)
+ * that are read multiple times during workspace scanning and unit initialization.
+ *
+ * **Clear Cache**: Call `FilesCache.clear()` to reset cache (useful for tests).
+ */
+export const FilesCache = {
+    /**
+     * Clears the file cache.
+     *
+     * Useful for tests or when files may have changed.
+     */
+    clear: () => cachedFiles = {},
+    load: {
+        /**
+         * Loads and caches a JSON file.
+         *
+         * **Behavior**:
+         * - Returns cached value if already loaded
+         * - Parses JSON and freezes result (immutable)
+         * - Throws `ImplementationMissingException` if file doesn't exist or is not a file
+         *
+         * @param pathToFile - Path to JSON file
+         * @returns Promise resolving to parsed and frozen JSON object
+         */
+        json: async (pathToFile) => {
+            const json = cachedFiles[pathToFile];
+            if (!json)
+                cachedFiles[pathToFile] = Object.freeze(JSON.parse(await readFile(pathToFile)));
+            return cachedFiles[pathToFile];
+        },
+        /**
+         * Loads and caches a text file.
+         *
+         * **Behavior**:
+         * - Returns cached value if already loaded
+         * - Reads file as UTF-8 text
+         * - Throws `ImplementationMissingException` if file doesn't exist or is not a file
+         *
+         * @param pathToFile - Path to text file
+         * @returns Promise resolving to file content as string
+         */
+        text: async (pathToFile) => {
+            const fileContent = cachedFiles[pathToFile];
+            if (!fileContent)
+                cachedFiles[pathToFile] = await readFile(pathToFile);
+            return cachedFiles[pathToFile];
+        }
+    }
+};