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

package/phases/PhaseManager.js

@@ -0,0 +1,267 @@
+import { addItemToArray, BadImplementationException, exists, flatArray, Logger, removeItemFromArray, timeCounter } from '@nu-art/ts-common';
+import { PhaseAggregatedException } from '../exceptions/PhaseAggregatedException.js';
+import { UnitPhaseException } from '../exceptions/UnitPhaseException.js';
+/**
+ * Manages phase execution across units in dependency order.
+ *
+ * **Execution Model**:
+ * - **Phase Groups**: Phases that can run in parallel (e.g., [prepare, compile])
+ * - **Unit Layers**: Units grouped by dependency level (dependencies first)
+ * - **Steps**: Combinations of phase groups × unit layers
+ *
+ * **Execution Flow**:
+ * 1. `calculateExecutionSteps()`: Plans which phases run on which units
+ * 2. `execute()`: Executes steps sequentially, phases in parallel within steps
+ * 3. Units in same layer run phases in parallel (Promise.all)
+ *
+ * **Eligibility Rules**:
+ * - Unit must implement the phase method (e.g., `compile()`, `test()`)
+ * - Unit must be in active/project units (based on phase.unitCategory)
+ * - Phase filter (if present) must pass runtime params
+ *
+ * **Error Handling**:
+ * - First failure stops execution (sets `killed = true`)
+ * - Aggregates all errors into `PhaseAggregatedException`
+ * - Tracks running units for graceful shutdown
+ *
+ * **Resume Support**:
+ * - Skips completed steps (via `runningStatus.startIndex`)
+ * - Skips completed units within steps (via `runningStatus.isCompleted()`)
+ *
+ * **Validation**:
+ * - Constructor validates no duplicate units or phases
+ * - Throws `BadImplementationException` on duplicates
+ */
+export class PhaseManager extends Logger {
+    phases;
+    units;
+    runningUnits = [];
+    killed = false;
+    runningStatus;
+    activeUnits;
+    projectUnitKeys;
+    keyToPhaseMap;
+    constructor(runningStatus, phases, units, activeUnits, projectUnitKeys) {
+        super();
+        this.phases = phases;
+        this.units = units;
+        this.runningStatus = runningStatus;
+        this.activeUnits = activeUnits;
+        this.projectUnitKeys = projectUnitKeys;
+        const unitsSet = new Set();
+        for (const unit of flatArray(this.units)) {
+            if (unitsSet.has(unit.config.key))
+                throw new BadImplementationException(`Found duplicate unit: '${unit.config.key}' in the project`);
+            unitsSet.add(unit.config.key);
+        }
+        const phasesSet = new Set();
+        const flatPhases = flatArray(this.phases);
+        for (const phase of flatPhases) {
+            if (phasesSet.has(phase.key))
+                throw new BadImplementationException(`Found duplicate phase '${phase.key}' in the project`);
+            phasesSet.add(phase.key);
+        }
+        this.keyToPhaseMap = flatPhases.reduce((acc, phase) => {
+            acc[phase.key] = phase;
+            return acc;
+        }, {});
+    }
+    //######################### Initialization #########################
+    /**
+     * Calculates the execution plan: which phases run on which units.
+     *
+     * **Algorithm**:
+     * 1. For each phase group (phases that can run together)
+     * 2. Filter phases by runtime params (if phase.filter exists)
+     * 3. For each unit layer (dependency level)
+     * 4. Find units eligible for at least one phase in the group
+     * 5. Group units by which phases they support
+     * 6. Create steps: phase combinations × unit groups
+     *
+     * **Phase Grouping**: Units that support the same set of phases are grouped
+     * together in a step (identified by phase keys joined with '|').
+     *
+     * **Unit Eligibility**:
+     * - Unit must implement phase method
+     * - Unit must be in active/project units (based on phase.unitCategory)
+     *
+     * @returns Array of scheduled steps (phases and unit keys)
+     */
+    async calculateExecutionSteps() {
+        const steps = [];
+        this.logDebug('Calculating execution steps for phases: ', this.phases.map(phases => phases.map(phase => phase.key)));
+        this.logDebug('Active Units: ', this.activeUnits);
+        this.logDebug('Project Units: ', this.projectUnitKeys);
+        for (let phaseGroup of this.phases) {
+            phaseGroup = phaseGroup.filter(phase => !exists(phase.filter) || phase.filter(this.runningStatus.runtimeParams));
+            for (const layer of this.units) {
+                // Determine eligible units for this phase group
+                // A unit is eligible if it's eligible for at least one phase in the group
+                const eligibleUnitKeys = new Set();
+                for (const phase of phaseGroup) {
+                    const unitCategory = phase.unitCategory ?? "active";
+                    const phaseEligibleKeys = unitCategory === "project" ? this.projectUnitKeys : this.activeUnits;
+                    phaseEligibleKeys.forEach(key => eligibleUnitKeys.add(key));
+                }
+                const layerUnits = layer.filter(u => eligibleUnitKeys.has(u.config.key));
+                if (layerUnits.length === 0)
+                    continue;
+                const phaseMap = new Map();
+                for (const unit of layerUnits) {
+                    // Find phases this unit supports and is eligible for
+                    const supportedPhases = phaseGroup.filter(phase => {
+                        if (!(phase.method in unit && typeof unit[phase.method] === 'function'))
+                            return false;
+                        // Check if unit is eligible for this specific phase
+                        const unitCategory = phase.unitCategory ?? "active";
+                        const phaseEligibleKeys = unitCategory === "project" ? this.projectUnitKeys : this.activeUnits;
+                        return phaseEligibleKeys.includes(unit.config.key);
+                    });
+                    if (supportedPhases.length === 0)
+                        continue;
+                    const key = phaseGroup
+                        .filter(phase => supportedPhases.find(p => p.key === phase.key))
+                        .map(p => p.key)
+                        .join('|');
+                    if (!phaseMap.has(key))
+                        phaseMap.set(key, []);
+                    phaseMap.get(key).push(unit);
+                }
+                for (const [phaseKeyCombo, groupedUnits] of phaseMap.entries()) {
+                    steps.push({
+                        phases: phaseKeyCombo.split('|'),
+                        units: groupedUnits.map(u => u.config.key),
+                    });
+                }
+            }
+        }
+        this.logVerbose('Calculated execution steps: ', steps);
+        return steps;
+    }
+    /**
+     * Executes the planned steps sequentially.
+     *
+     * **Execution Model**:
+     * - Steps run sequentially (one after another)
+     * - Units within a step run phases in parallel (Promise.all)
+     * - Phases for a unit run sequentially (in phase group order)
+     *
+     * **Resume Support**:
+     * - Starts from `runningStatus.startIndex` (if --continue)
+     * - Skips units marked as completed
+     *
+     * **Dry Run**: If `--dry-run`, only logs phase/unit names without executing.
+     *
+     * **Error Handling**:
+     * - First error stops execution (sets `killed = true`)
+     * - All errors aggregated into `PhaseAggregatedException`
+     * - Running units tracked for graceful shutdown
+     *
+     * **Performance**: Logs operation duration if > 1.5 seconds.
+     *
+     * @param _steps - Scheduled steps to execute
+     * @throws PhaseAggregatedException if any phase fails
+     */
+    async execute(_steps) {
+        this.runningUnits = [];
+        for (let i = this.runningStatus.startIndex; i < _steps.length; i++) {
+            if (this.killed)
+                break;
+            const scheduledStep = _steps[i];
+            const step = this.mapStep(scheduledStep);
+            await this.runningStatus.onStepStarted(i);
+            this.logDebug(`Executing step #${i + 1}/${_steps.length}`);
+            this.logVerbose(scheduledStep);
+            const errors = [];
+            let failedStep;
+            await Promise.all(step.units.map(async (unit) => {
+                if (this.runningStatus.isCompleted(unit.config.key))
+                    return;
+                let failed = false;
+                for (const phase of step.phases) {
+                    if (this.killed)
+                        break;
+                    if (this.runningStatus.runtimeParams.dryRun) {
+                        this.logInfo(`[${phase.key}] - ${unit.config.key}`);
+                        continue;
+                    }
+                    addItemToArray(this.runningUnits, unit);
+                    const dtCounter = timeCounter();
+                    try {
+                        this.logInfo(`Phase(${phase.name}) - Running - ${unit.config.key}`);
+                        if (typeof unit[phase.method] === 'function')
+                            await unit[phase.method].call(unit);
+                        let operationDuration = '';
+                        if (dtCounter.dt() > 1500)
+                            operationDuration = ` (${dtCounter.format('mm:ss')})`;
+                        this.logInfo(`Phase(${phase.name}) - Completed${operationDuration} - ${unit.config.key}`);
+                    }
+                    catch (error) {
+                        this.logError(`Phase(${phase.name}) - Error - ${unit.config.key}`, error);
+                        errors.push(new UnitPhaseException(error, unit, phase.key));
+                        failedStep = scheduledStep;
+                        this.killed = true;
+                        failed = true;
+                        break;
+                    }
+                    finally {
+                        removeItemFromArray(this.runningUnits, unit);
+                    }
+                }
+                if (!failed)
+                    await this.runningStatus.onUnitCompleted(unit.config.key);
+            }));
+            if (failedStep && errors.length) {
+                throw new PhaseAggregatedException(errors, failedStep);
+            }
+            await this.runningStatus.onStepEnded();
+        }
+        this.logInfo('All steps completed.');
+    }
+    /**
+     * Gracefully stops execution and kills all running units.
+     *
+     * Called on SIGINT (Ctrl+C). Sets `killed = true` to stop further execution,
+     * then calls `kill()` on all currently running units.
+     *
+     * @returns Promise that resolves when all units are killed
+     */
+    break() {
+        this.killed = true;
+        return Promise.all(this.runningUnits.map(unit => unit.kill()));
+    }
+    /**
+     * Maps scheduled step (with string keys) to execution step (with actual instances).
+     *
+     * **Mapping Process**:
+     * - Maps phase keys to Phase instances using `keyToPhaseMap`
+     * - Maps unit keys to BaseUnit instances by searching through unit layers
+     *
+     * **Performance Note**: Unit lookup iterates through all layers (O(n) complexity).
+     * Consider using a lookup map for O(1) access in large workspaces.
+     *
+     * @param scheduledStep - Scheduled step with phase/unit keys
+     * @returns Execution step with phase/unit instances
+     * @throws Error if phase or unit not found
+     */
+    mapStep(scheduledStep) {
+        const mappedPhases = scheduledStep.phases.map(phaseKey => {
+            const phase = this.keyToPhaseMap[phaseKey];
+            if (!phase)
+                throw new Error(`Phase '${phaseKey}' not found in PhaseManager.phases`);
+            return phase;
+        });
+        const mappedUnits = scheduledStep.units.map(unitKey => {
+            for (const layer of this.units) {
+                const unit = layer.find(u => u.config.key === unitKey);
+                if (unit)
+                    return unit;
+            }
+            throw new Error(`Unit '${unitKey}' not found in PhaseManager.units`);
+        });
+        return {
+            phases: mappedPhases,
+            units: mappedUnits
+        };
+    }
+}

package/{v3/phase → phases/definitions}/consts.d.ts

@@ -1,3 +1,24 @@
+/**
+ * Phase definitions for the build system.
+ *
+ * **Phase Groups**:
+ * - `phases_Terminating`: Phases that terminate execution after completion
+ * - `phases_Build`: Main build phases (purge, prepare, install, compile, test, etc.)
+ * - `phases_Launch`: Launch phases (start applications)
+ * - `phases_Deploy`: Deployment phases
+ *
+ * **Phase Execution Order**:
+ * 1. Build phases run first (prepare, install, compile, test)
+ * 2. Terminating phases can stop execution early
+ * 3. Launch phases start applications
+ * 4. Deploy phases publish/deploy
+ *
+ * **Phase Filters**: Most phases have filters based on runtime params (e.g., `--lint`, `--test`).
+ * Phases only run if their filter returns true (or no filter is present).
+ *
+ * **Dependency Phases**: Some phases depend on others (e.g., `compile` depends on `preCompile`).
+ * Dependencies are automatically resolved by PhaseManager.
+ */
 import { Phase } from './types.js';
 export type Phase_PrintDependencyTree = typeof phase_PrintDependencyTree;
 export declare const phaseKey_PrintDependencyTree = "print-dependency-tree";
@@ -24,6 +45,12 @@ export declare const phase_Lint: Phase<'lint'>;
 export type Phase_PreCompile = typeof phase_PreCompile;
 export declare const phaseKey_PreCompile = "preCompile";
 export declare const phase_PreCompile: Phase<'preCompile'>;
+export type Phase_ExtractDynamicDeps = typeof phase_ExtractDynamicDeps;
+export declare const phaseKey_ExtractDynamicDeps = "extract-dynamic-deps";
+export declare const phase_ExtractDynamicDeps: Phase<'extractDynamicDeps'>;
+export type Phase_MapExports = typeof phase_MapExports;
+export declare const phaseKey_MapExports = "map-exports";
+export declare const phase_MapExports: Phase<'mapExports'>;
 export type Phase_Compile = typeof phase_Compile;
 export declare const phaseKey_Compile = "compile";
 export declare const phase_Compile: Phase<'compile'>;
@@ -40,6 +67,9 @@ export declare const phases_Build: Phase<string>[][];
 export type Phase_Launch = typeof phase_Launch;
 export declare const phaseKey_Launch = "launch";
 export declare const phase_Launch: Phase<'launch'>;
+export type Phase_IndicesMcpServer = typeof phase_IndicesMcpServer;
+export declare const phaseKey_IndicesMcpServer = "indices-mcp-server";
+export declare const phase_IndicesMcpServer: Phase<'indicesMcpServer'>;
 export declare const phases_Launch: Phase<string>[][];
 export type Phase_Publish = typeof phase_Publish;
 export declare const phaseKey_Publish = "publish";
@@ -50,4 +80,10 @@ export declare const phase_PostPublish: Phase<'postPublish'>;
 export type Phase_Deploy = typeof phase_Deploy;
 export declare const phaseKey_Deploy = "deploy";
 export declare const phase_Deploy: Phase<'deploy'>;
+export type Phase_BuildPushImage = typeof phase_BuildPushImage;
+export declare const phaseKey_BuildPushImage = "build-push-image";
+export declare const phase_BuildPushImage: Phase<'buildPushImage'>;
+export type Phase_DeployImage = typeof phase_DeployImage;
+export declare const phaseKey_DeployImage = "deploy-image";
+export declare const phase_DeployImage: Phase<'deployImage'>;
 export declare const phases_Deploy: Phase<string>[][];

package/{v3/phase → phases/definitions}/consts.js

@@ -38,6 +38,7 @@ export const phase_Prepare = {
     name: 'Prepare',
     method: 'prepare',
     filter: (baiParams) => baiParams.prepare,
+    unitCategory: "project", // All project units need to be prepared
 };
 export const phaseKey_Install = 'install';
 export const phase_Install = {
@@ -61,6 +62,20 @@ export const phase_PreCompile = {
     method: 'preCompile',
     filter: (baiParams) => !baiParams.noBuild,
 };
+export const phaseKey_ExtractDynamicDeps = 'extract-dynamic-deps';
+export const phase_ExtractDynamicDeps = {
+    key: phaseKey_ExtractDynamicDeps,
+    name: 'Extract Dynamic Dependencies',
+    method: 'extractDynamicDeps',
+    filter: (baiParams) => baiParams.extractDynamicDeps,
+};
+export const phaseKey_MapExports = 'map-exports';
+export const phase_MapExports = {
+    key: phaseKey_MapExports,
+    name: 'Map Exports',
+    method: 'mapExports',
+    filter: (baiParams) => baiParams.mapExports,
+};
 export const phaseKey_Compile = 'compile';
 export const phase_Compile = {
     key: phaseKey_Compile,
@@ -94,7 +109,7 @@ export const phases_Build = [
     [phase_Purge, phase_Prepare],
     [phase_ToESM],
     [phase_Install],
-    [phase_Lint, phase_PreCompile, phase_Compile, phase_Test,],
+    [phase_Lint, phase_PreCompile, phase_ExtractDynamicDeps, phase_MapExports, phase_Compile, phase_Test,],
     [phase_Watch]
 ];
 export const phaseKey_Launch = 'launch';
@@ -104,8 +119,16 @@ export const phase_Launch = {
     method: 'launch',
     filter: (baiParams) => !!baiParams.launch,
 };
+export const phaseKey_IndicesMcpServer = 'indices-mcp-server';
+export const phase_IndicesMcpServer = {
+    key: phaseKey_IndicesMcpServer,
+    name: 'Export Indices MCP Server',
+    method: 'indicesMcpServer',
+    filter: (baiParams) => baiParams.indicesMcpServer,
+};
 export const phases_Launch = [[
         phase_Launch,
+        phase_IndicesMcpServer,
     ]];
 export const phaseKey_Publish = 'publish';
 export const phase_Publish = {
@@ -128,4 +151,24 @@ export const phase_Deploy = {
     method: 'deploy',
     filter: (baiParams) => !!baiParams.deploy,
 };
-export const phases_Deploy = [[phase_Publish, phase_Deploy], [phase_PostPublish]];
+export const phaseKey_BuildPushImage = 'build-push-image';
+export const phase_BuildPushImage = {
+    key: phaseKey_BuildPushImage,
+    name: 'Build & Push Container Image',
+    method: 'buildPushImage',
+    filter: (baiParams) => !!baiParams.buildPushImage,
+};
+export const phaseKey_DeployImage = 'deploy-image';
+export const phase_DeployImage = {
+    key: phaseKey_DeployImage,
+    name: 'Deploy Container Image',
+    method: 'deployImage',
+    filter: (baiParams) => !!baiParams.deployImage,
+    dependencyPhase: [phase_BuildPushImage],
+};
+export const phases_Deploy = [
+    [phase_BuildPushImage],
+    [phase_DeployImage],
+    [phase_Publish, phase_Deploy],
+    [phase_PostPublish]
+];

package/phases/definitions/types.d.ts

@@ -0,0 +1,40 @@
+import { BaiParams } from '../../core/params.js';
+/**
+ * Phase definition for build system execution.
+ *
+ * **Phase Structure**:
+ * - Phases are grouped into phase groups (arrays of phases)
+ * - Phases in a group can run in parallel
+ * - Phase groups run sequentially
+ *
+ * **Key Properties**:
+ * - `key`: Unique identifier for the phase
+ * - `method`: Method name that units must implement (e.g., 'compile', 'test')
+ * - `filter`: Optional function to determine if phase should run based on runtime params
+ * - `unitCategory`: Which units participate ('active' or 'project')
+ * - `dependencyPhase`: Phases that must complete before this phase runs
+ * - `terminateAfterPhase`: If true, stops execution after this phase completes
+ *
+ * **Unit Participation**:
+ * - Units must implement the phase method to participate
+ * - Units must be in the correct category (active/project)
+ * - Phase filter must pass (if present)
+ *
+ * **Examples**: See `phase/consts.ts` for all phase definitions.
+ */
+export type Phase<PhaseMethod extends string> = {
+    /** Unique identifier for the phase */
+    key: string;
+    /** Display name for the phase */
+    name: string;
+    /** Method name that units must implement */
+    method: PhaseMethod;
+    /** Optional filter to determine if phase should run based on runtime params */
+    filter?: (params: BaiParams) => boolean;
+    /** If true, terminates execution after this phase completes */
+    terminateAfterPhase?: boolean;
+    /** Phases that must complete before this phase runs */
+    dependencyPhase?: Phase<string>[];
+    /** Unit category: 'project' = all project units (active + dependencies), 'active' = only active units (default) */
+    unitCategory?: "project" | "active";
+};

package/phases/index.d.ts

@@ -0,0 +1,2 @@
+export * from './definitions/index.js';
+export * from './PhaseManager.js';

package/phases/index.js

@@ -0,0 +1,2 @@
+export * from './definitions/index.js';
+export * from './PhaseManager.js';

package/run.js

@@ -0,0 +1,10 @@
+import { BuildAndInstall } from './BuildAndInstall.js';
+(async () => {
+    const buildAndInstall = new BuildAndInstall();
+    await buildAndInstall.build();
+    await buildAndInstall.run();
+})()
+    .catch((err) => {
+    process.exit(2);
+})
+    .then(() => process.exit(0));

package/runtime/RunningStatusHandler.d.ts

@@ -0,0 +1,104 @@
+import { Logger } from '@nu-art/ts-common';
+import { BaiParams } from '../core/params.js';
+/**
+ * Manages execution state persistence for resume support.
+ *
+ * **Purpose**: Enables `--continue` flag to resume from last completed step.
+ *
+ * **State Management**:
+ * - **startIndex**: Current step index (0-based)
+ * - **completedUnits**: Units completed in current step
+ * - **runtimeParams**: Runtime parameters (for state validation)
+ *
+ * **Persistence**:
+ * - Saves state to `.trash/output/running-status.json` after each step/unit
+ * - Loads state on init if `--continue` flag is set
+ * - State includes: index, runtimeParams, completedUnits
+ *
+ * **Isolation Mode**: When isolated, skips saving state (useful for tests).
+ *
+ * **Usage Flow**:
+ * 1. `init()` - Loads state if `--continue`
+ * 2. `onStepStarted()` - Saves current step index
+ * 3. `onUnitCompleted()` - Marks unit as completed, saves state
+ * 4. `onStepEnded()` - Clears completed units for next step
+ * 5. `isCompleted()` - Checks if unit already completed (for resume)
+ */
+export declare class RunningStatusHandler extends Logger {
+    private isolated;
+    private readonly outputFolder;
+    private completedUnits;
+    runtimeParams: BaiParams;
+    startIndex: number;
+    constructor(outputFolder: string, runtimeParams: BaiParams);
+    /**
+     * Initializes the status handler.
+     *
+     * **Actions**:
+     * - Creates output folder if missing
+     * - Loads saved state if `--continue` flag is set
+     * - Merges loaded runtime params with current params (loaded params take precedence)
+     */
+    init(): Promise<void>;
+    /**
+     * Enables isolation mode (skips saving state).
+     *
+     * Useful for tests or when state persistence is not desired.
+     *
+     * @returns This instance for chaining
+     */
+    isolate(): RunningStatusHandler;
+    /**
+     * Checks if a unit has already been completed (for resume).
+     *
+     * @param unitKey - Unit key to check
+     * @returns True if unit is marked as completed
+     */
+    isCompleted(unitKey: string): boolean;
+    /**
+     * Marks a unit as completed and saves state.
+     *
+     * Called after a unit successfully completes all its phases.
+     *
+     * @param unitKey - Unit key that completed
+     */
+    onUnitCompleted(unitKey: string): Promise<void>;
+    /**
+     * Called when a step completes successfully.
+     *
+     * Clears completed units list for the next step.
+     */
+    onStepEnded(): Promise<void>;
+    /**
+     * Called when a step starts.
+     *
+     * Updates start index and saves state (unless isolated).
+     *
+     * @param index - Step index (0-based)
+     */
+    onStepStarted(index: number): Promise<void>;
+    /**
+     * Saves current state to disk.
+     *
+     * Writes to `.trash/output/running-status.json` with:
+     * - Current step index
+     * - Runtime params (for validation)
+     * - Completed units in current step
+     *
+     * Called after each step start and unit completion.
+     */
+    private saveStatus;
+    /**
+     * Loads saved state from disk.
+     *
+     * **Behavior**:
+     * - Reads from `.trash/output/running-status.json`
+     * - Restores step index, completed units, and runtime params
+     * - Returns undefined if file doesn't exist or parse fails (logs error)
+     *
+     * **Note**: Runtime params from file override current params (for consistency).
+     *
+     * @returns Promise resolving to step index, or undefined if load fails
+     */
+    load(): Promise<any>;
+}