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

package/units/discovery/resolvers/UnitMapper_Base.js

@@ -0,0 +1,46 @@
+import { Logger } from '@nu-art/ts-common';
+/**
+ * Base class for unit mapper resolvers.
+ *
+ * **Purpose**: Each mapper resolver checks if a directory path matches its unit type
+ * and creates the appropriate unit instance if it matches.
+ *
+ * **Resolution Process**:
+ * 1. `resolveUnit()` is called for each directory during workspace scan
+ * 2. Mapper checks if path matches its criteria (package.json type, file presence, etc.)
+ * 3. If match, creates and returns unit instance
+ * 4. If no match, returns undefined (next mapper tries)
+ *
+ * **Configuration**:
+ * - `validator`: Validates unit config JSON (e.g., package.json.unitConfig.type)
+ * - `baiConfig`: BAI configuration (set by UnitsMapper)
+ * - `runtimeParams`: Runtime parameters (set by UnitsMapper)
+ *
+ * **Usage**: Extended by specific mappers (UnitMapper_NodeLib, UnitMapper_FirebaseFunction, etc.)
+ * to implement unit-specific discovery logic.
+ */
+export class UnitMapper_Base extends Logger {
+    validator;
+    baiConfig;
+    runtimeParams;
+    constructor(validator) {
+        super();
+        this.validator = validator;
+    }
+    /**
+     * Sets runtime parameters for the mapper.
+     *
+     * Called by UnitsMapper to provide runtime context.
+     */
+    setRuntimeParams(runtimeParams) {
+        this.runtimeParams = runtimeParams;
+    }
+    /**
+     * Sets BAI configuration for the mapper.
+     *
+     * Called by UnitsMapper to provide configuration context.
+     */
+    setConfig(config) {
+        this.baiConfig = config;
+    }
+}

package/{v3/UnitsMapper → units/discovery}/resolvers/UnitMapper_FirebaseFunction.d.ts

@@ -1,10 +1,9 @@
 import { TypedMap } from '@nu-art/ts-common';
 import { UnitConfigJSON_Node, UnitMapper_Node, UnitMapper_NodeContext } from './UnitMapper_Node.js';
-import { Unit_FirebaseFunctionsApp } from '../../units/firebase/Unit_FirebaseFunctionsApp.js';
+import { FunctionConfig, Unit_FirebaseFunctionsApp } from '../../implementations/firebase/Unit_FirebaseFunctionsApp.js';
 type EnvConfig = {
     defaultConfig?: string;
     envConfig?: string;
-    identityAccount?: string;
     projectId: string;
     isLocal?: boolean;
 };
@@ -15,6 +14,7 @@ type UnitConfigJSON_FirebaseFunction = UnitConfigJSON_Node & {
     ignore?: string[];
     sslKey?: string;
     sslCert?: string;
+    functions: string[] | FunctionConfig[];
 };
 export declare class UnitMapper_FirebaseFunction_Class extends UnitMapper_Node<Unit_FirebaseFunctionsApp, UnitConfigJSON_FirebaseFunction> {
     static tsValidator_FirebaseFunction: {
@@ -29,11 +29,12 @@ export declare class UnitMapper_FirebaseFunction_Class extends UnitMapper_Node<U
         basePort: import("@nu-art/ts-common").Validator<number>;
         sslKey: import("@nu-art/ts-common").Validator<string>;
         sslCert: import("@nu-art/ts-common").Validator<string>;
+        functions: import("@nu-art/ts-common").Validator<FunctionConfig[]>;
+        containerDeployment: (import("@nu-art/ts-common").ValidatorImpl<any> | ((input?: object | undefined) => string | object | undefined))[];
     };
     constructor();
     protected resolveNodeUnit(context: UnitMapper_NodeContext<UnitConfigJSON_FirebaseFunction>): Promise<Unit_FirebaseFunctionsApp<{
         envConfig: {
-            identityAccount: string | undefined;
             defaultConfig: string | undefined;
             envConfig: string | undefined;
             projectId: string;
@@ -52,6 +53,7 @@ export declare class UnitMapper_FirebaseFunction_Class extends UnitMapper_Node<U
         basePort: number;
         envs: TypedMap<EnvConfig>;
         ignore?: string[] | undefined;
+        functions: string[] | FunctionConfig[];
         pathToFirebaseConfig: string;
         pathToEmulatorData: string;
         fullPath: import("@nu-art/ts-common").AbsolutePath;

package/units/discovery/resolvers/UnitMapper_FirebaseFunction.js

@@ -0,0 +1,105 @@
+import { ImplementationMissingException, tsValidate_OptionalArray, tsValidateAnyNumber, tsValidateAnyString, tsValidateBoolean, tsValidateDynamicObject, tsValidateOptionalAnyNumber, tsValidateOptionalAnyString, tsValidateOptionalObject, tsValidateRegexp, tsValidateResult, tsValidateValue } from '@nu-art/ts-common';
+import { UnitMapper_Node } from './UnitMapper_Node.js';
+import { Unit_FirebaseFunctionsApp } from '../../implementations/firebase/Unit_FirebaseFunctionsApp.js';
+import { resolve } from 'path';
+import { BaiParam_SetEnv } from '../../../core/params.js';
+const valuesValidator = {
+    defaultConfig: tsValidateOptionalAnyString,
+    envConfig: tsValidateOptionalAnyString,
+    projectId: tsValidateAnyString,
+    isLocal: tsValidateBoolean(false),
+};
+// Docker image name validation: lowercase, alphanumeric with dots, underscores, hyphens
+// Cannot start/end with separators, no consecutive separators
+// Pattern: starts with alphanumeric, optionally followed by (separator + alphanumeric) groups
+const imageNameRegex = /^[a-z0-9]+([._-][a-z0-9]+)*$/;
+const containerDeploymentValidator = {
+    artifactRegistry: {
+        region: tsValidateAnyString,
+        repository: tsValidateAnyString,
+        projectId: tsValidateAnyString,
+    },
+    imageName: tsValidateRegexp(imageNameRegex, true), // Required: Docker image name matching Artifact Registry rules
+    dockerfile: tsValidateOptionalAnyString,
+};
+// Validator for FunctionResourceConfig
+const functionResourceConfigValidator = {
+    cpu: tsValidateAnyNumber,
+    memory: tsValidateOptionalAnyString,
+    timeout: tsValidateOptionalAnyNumber,
+    concurrency: tsValidateOptionalAnyNumber,
+    minInstances: tsValidateOptionalAnyNumber,
+    maxInstances: tsValidateOptionalAnyNumber,
+};
+// Validator for FunctionConfig
+const functionConfigValidator = {
+    name: tsValidateAnyString,
+    trigger: tsValidateValue(['http', 'schedule', 'eventarc']),
+    schedule: tsValidateOptionalAnyString,
+    serviceAccountName: tsValidateOptionalAnyString,
+    resources: tsValidateOptionalObject(functionResourceConfigValidator),
+};
+// Validator for functions array: accepts either string[] or FunctionConfig[]
+// Uses custom validator to check type first, then validate accordingly
+const functionItemValidator = (input) => {
+    if (typeof input === 'string') {
+        // Legacy format: just a string (function name)
+        return tsValidateResult(input, tsValidateAnyString);
+    }
+    if (typeof input === 'object' && input !== null) {
+        // New format: FunctionConfig object
+        return tsValidateResult(input, tsValidateOptionalObject(functionConfigValidator));
+    }
+    return 'Function item must be either a string (function name) or an object (FunctionConfig)';
+};
+const functionsArrayValidator = tsValidate_OptionalArray(functionItemValidator);
+export class UnitMapper_FirebaseFunction_Class extends UnitMapper_Node {
+    static tsValidator_FirebaseFunction = {
+        type: tsValidateValue(['firebase-function']),
+        ignore: tsValidate_OptionalArray(tsValidateOptionalAnyString),
+        envs: tsValidateDynamicObject(valuesValidator, tsValidateAnyString),
+        debugPort: tsValidateOptionalAnyNumber,
+        basePort: tsValidateOptionalAnyNumber,
+        sslKey: tsValidateOptionalAnyString,
+        sslCert: tsValidateOptionalAnyString,
+        functions: functionsArrayValidator, // Required: non-empty array validated in process, accepts string[] or FunctionConfig[]
+        containerDeployment: tsValidateOptionalObject(containerDeploymentValidator),
+        ...UnitMapper_Node.tsValidator_Node,
+    };
+    constructor() {
+        super(UnitMapper_FirebaseFunction_Class.tsValidator_FirebaseFunction);
+    }
+    async resolveNodeUnit(context) {
+        const outputDir = context.packageJson.publishConfig?.directory;
+        const env = this.runtimeParams[BaiParam_SetEnv.keyName];
+        const envUnitConfig = context.packageJson.unitConfig.envs[env];
+        if (!envUnitConfig)
+            throw new ImplementationMissingException(`Missing configuration for env: ${env}`);
+        const envConfig = {
+            defaultConfig: envUnitConfig.defaultConfig,
+            envConfig: envUnitConfig.envConfig,
+            projectId: envUnitConfig.projectId,
+            isLocal: envUnitConfig.isLocal ?? env === 'local'
+        };
+        const { type, ...unitConfig } = context.packageJson.unitConfig;
+        // Validate functions array is required and non-empty
+        if (!unitConfig.functions || !Array.isArray(unitConfig.functions) || unitConfig.functions.length === 0) {
+            throw new ImplementationMissingException(`Missing or empty 'functions' array in unit config for ${context.baseConfig.key}. Functions must be explicitly declared.`);
+        }
+        return new Unit_FirebaseFunctionsApp({
+            ...context.baseConfig,
+            ...Unit_FirebaseFunctionsApp.DefaultConfig_FirebaseFunction,
+            ...unitConfig,
+            envConfig,
+            isTopLevelApp: true,
+            hasSelfHotReload: unitConfig.hasSelfHotReload ?? false,
+            packageJson: context.packageJson,
+            customESLintConfig: context.customESLintConfig,
+            customTSConfig: context.customTSConfig,
+            output: resolve(context.baseConfig.fullPath, outputDir ?? Unit_FirebaseFunctionsApp.DefaultConfig_FirebaseFunction.output),
+            sslCert: resolve(context.baseConfig.fullPath, unitConfig.sslCert ?? Unit_FirebaseFunctionsApp.DefaultConfig_FirebaseFunction.sslCert),
+            sslKey: resolve(context.baseConfig.fullPath, unitConfig.sslKey ?? Unit_FirebaseFunctionsApp.DefaultConfig_FirebaseFunction.sslKey),
+        });
+    }
+}
+export const UnitMapper_FirebaseFunction = new UnitMapper_FirebaseFunction_Class();

package/{v3/UnitsMapper → units/discovery}/resolvers/UnitMapper_FirebaseHosting.d.ts

@@ -1,6 +1,6 @@
 import { TypedMap } from '@nu-art/ts-common';
 import { UnitMapper_Node, UnitMapper_NodeContext } from './UnitMapper_Node.js';
-import { FirebaseHosting_EnvConfig, Unit_FirebaseHostingApp, UnitConfigJSON_FirebaseHosting } from '../../units/firebase/Unit_FirebaseHostingApp.js';
+import { FirebaseHosting_EnvConfig, Unit_FirebaseHostingApp, UnitConfigJSON_FirebaseHosting } from '../../implementations/firebase/Unit_FirebaseHostingApp.js';
 export declare class UnitMapper_FirebaseHosting_Class extends UnitMapper_Node<Unit_FirebaseHostingApp, UnitConfigJSON_FirebaseHosting> {
     static tsValidator_FirebaseHosting: {
         label: import("@nu-art/ts-common").Validator<string>;
@@ -11,6 +11,7 @@ export declare class UnitMapper_FirebaseHosting_Class extends UnitMapper_Node<Un
         servingPort: import("@nu-art/ts-common").Validator<number>;
         envs: (import("@nu-art/ts-common").ValidatorImpl<any> | ((input?: TypedMap<FirebaseHosting_EnvConfig> | undefined) => import("@nu-art/ts-common").InvalidResultObject<TypedMap<FirebaseHosting_EnvConfig>> | undefined))[];
         hostingConfig: import("@nu-art/ts-common").ValidatorImpl<any>;
+        hostingDeployment: (import("@nu-art/ts-common").ValidatorImpl<any> | ((input?: object | undefined) => string | object | undefined))[];
     };
     constructor();
     protected resolveNodeUnit(context: UnitMapper_NodeContext<UnitConfigJSON_FirebaseHosting>): Promise<Unit_FirebaseHostingApp<{
@@ -27,7 +28,7 @@ export declare class UnitMapper_FirebaseHosting_Class extends UnitMapper_Node<Un
         packageJson: import("../types.js").TS_PackageJSON<UnitConfigJSON_FirebaseHosting>;
         label: string;
         servingPort: number;
-        hostingConfig?: import("../../units/firebase/Unit_FirebaseHostingApp.js").FirebaseHostingConfig | undefined;
+        hostingConfig?: import("../../implementations/firebase/Unit_FirebaseHostingApp.js").FirebaseHostingConfig | undefined;
         envs: TypedMap<FirebaseHosting_EnvConfig>;
         fullPath: import("@nu-art/ts-common").AbsolutePath;
         relativePath: import("@nu-art/ts-common").RelativePath;

package/{v3/UnitsMapper → units/discovery}/resolvers/UnitMapper_FirebaseHosting.js

@@ -1,19 +1,27 @@
-import { tsValidateAnyString, tsValidateBoolean, tsValidateDynamicObject, tsValidateMustExist, tsValidateOptional, tsValidateOptionalAnyNumber, tsValidateValue } from '@nu-art/ts-common';
+import { ImplementationMissingException, tsValidateAnyString, tsValidateBoolean, tsValidateDynamicObject, tsValidateMustExist, tsValidateOptional, tsValidateOptionalAnyNumber, tsValidateOptionalObject, tsValidateValue } from '@nu-art/ts-common';
 import { UnitMapper_Node } from './UnitMapper_Node.js';
-import { Unit_FirebaseHostingApp } from '../../units/firebase/Unit_FirebaseHostingApp.js';
+import { Unit_FirebaseHostingApp } from '../../implementations/firebase/Unit_FirebaseHostingApp.js';
 import { resolve } from 'path';
-import { BaiParam_SetEnv } from '../../../core/params/params.js';
+import { BaiParam_SetEnv } from '../../../core/params.js';
 const valuesValidator = {
     config: tsValidateMustExist,
     projectId: tsValidateAnyString,
     isLocal: tsValidateBoolean(false),
 };
+const hostingDeploymentValidator = {
+    artifactRegistry: {
+        region: tsValidateAnyString,
+        repository: tsValidateAnyString,
+        projectId: tsValidateAnyString,
+    },
+};
 export class UnitMapper_FirebaseHosting_Class extends UnitMapper_Node {
     static tsValidator_FirebaseHosting = {
         type: tsValidateValue(['firebase-hosting']),
         servingPort: tsValidateOptionalAnyNumber,
         envs: tsValidateDynamicObject(valuesValidator, tsValidateAnyString),
         hostingConfig: tsValidateOptional,
+        hostingDeployment: tsValidateOptionalObject(hostingDeploymentValidator),
         ...UnitMapper_Node.tsValidator_Node,
     };
     constructor() {
@@ -22,14 +30,10 @@ export class UnitMapper_FirebaseHosting_Class extends UnitMapper_Node {
     async resolveNodeUnit(context) {
         const outputDir = context.packageJson.publishConfig?.directory;
         const env = this.runtimeParams[BaiParam_SetEnv.keyName];
-        let envUnitConfig = context.packageJson.unitConfig.envs[env];
+        const envUnitConfig = context.packageJson.unitConfig.envs[env];
         if (!envUnitConfig) {
-            this.logWarning(`Missing EnvConfig in unit ${context.baseConfig.key}`);
-            envUnitConfig = {
-                config: {},
-                projectId: '',
-                isLocal: true
-            };
+            this.logWarning('Package Json config:', context.packageJson.unitConfig);
+            throw new ImplementationMissingException(`Missing configuration for env: ${env}`);
         }
         const envConfig = {
             config: envUnitConfig.config,

package/{v3/UnitsMapper → units/discovery}/resolvers/UnitMapper_Node.d.ts

@@ -1,6 +1,6 @@
 import { TS_PackageJSON } from '../types.js';
 import { TypeValidator } from '@nu-art/ts-common';
-import { BaseUnit } from '../../units/index.js';
+import { BaseUnit } from '../../index.js';
 import { BaseUnitConfig, UnitConfigJSON_Base, UnitMapper_Base } from './UnitMapper_Base.js';
 export type UnitConfigJSON_Node = UnitConfigJSON_Base & {
     label: string;

package/{v3/UnitsMapper → units/discovery}/resolvers/UnitMapper_Node.js

@@ -1,5 +1,5 @@
 import { _keys, deepClone, tsValidate, tsValidateBoolean, tsValidateOptionalAnyString, tsValidateResult } from '@nu-art/ts-common';
-import { FilesCache } from '../../core/FilesCache.js';
+import { FilesCache } from '../../../core/FilesCache.js';
 import { UnitMapper_Base } from './UnitMapper_Base.js';
 import { FileSystemUtils } from '@nu-art/ts-common/utils/FileSystemUtils';
 export class UnitMapper_Node extends UnitMapper_Base {
@@ -32,7 +32,7 @@ export class UnitMapper_Node extends UnitMapper_Base {
             if (tsValidateResult(packageJson.unitConfig.type, this.validator.type))
                 return; // not the expected type for this mapper
             packageJson = deepClone(packageJson);
-            tsValidate(packageJson.unitConfig, this.validator, false);
+            tsValidate(packageJson.unitConfig, this.validator);
             const dependencies = packageJson.dependencies;
             if (dependencies)
                 packageJson.dependencies = _keys(dependencies).reduce((acc, key) => {

package/{v3/UnitsMapper → units/discovery}/resolvers/UnitMapper_NodeLib.d.ts

@@ -1,5 +1,21 @@
-import { Unit_TypescriptLib } from '../../units/index.js';
+import { Unit_TypescriptLib } from '../../implementations/Unit_TypescriptLib.js';
 import { UnitMapper_Node, UnitMapper_NodeContext } from './UnitMapper_Node.js';
+/**
+ * Mapper for discovering TypeScript library units.
+ *
+ * **Discovery Criteria**:
+ * - Must have `package.json` with `unitConfig.type === 'typescript-lib'`
+ * - Must have `publishConfig.directory` (output directory)
+ * - Must have TypeScript source files
+ *
+ * **Unit Creation**:
+ * - Creates `Unit_TypescriptLib` instance
+ * - Configures output directory from `publishConfig.directory`
+ * - Sets hot reload flag from `unitConfig.hasSelfHotReload`
+ * - Detects custom ESLint/TSConfig files
+ *
+ * **Usage**: Automatically registered by `BuildAndInstall.prepareUnitsMapper()`.
+ */
 export declare class UnitMapper_NodeLib_Class extends UnitMapper_Node<Unit_TypescriptLib> {
     static tsValidator_NodeProject: {
         label: import("@nu-art/ts-common").Validator<string>;
@@ -9,6 +25,13 @@ export declare class UnitMapper_NodeLib_Class extends UnitMapper_Node<Unit_Types
         type: import("@nu-art/ts-common").Validator<any>;
     };
     constructor();
+    /**
+     * Creates a Unit_TypescriptLib instance from resolved context.
+     *
+     * @param context - Resolved node unit context
+     * @returns Unit_TypescriptLib instance
+     * @throws BadImplementationException if publishConfig.directory is missing
+     */
     protected resolveNodeUnit(context: UnitMapper_NodeContext): Promise<Unit_TypescriptLib<{
         hasSelfHotReload: boolean;
         customESLintConfig: boolean;

package/{v3/UnitsMapper → units/discovery}/resolvers/UnitMapper_NodeLib.js

@@ -1,7 +1,23 @@
-import { Unit_TypescriptLib } from '../../units/index.js';
+import { Unit_TypescriptLib } from '../../implementations/Unit_TypescriptLib.js';
 import { BadImplementationException, tsValidateValue } from '@nu-art/ts-common';
 import { UnitMapper_Node } from './UnitMapper_Node.js';
 import { resolve } from 'path';
+/**
+ * Mapper for discovering TypeScript library units.
+ *
+ * **Discovery Criteria**:
+ * - Must have `package.json` with `unitConfig.type === 'typescript-lib'`
+ * - Must have `publishConfig.directory` (output directory)
+ * - Must have TypeScript source files
+ *
+ * **Unit Creation**:
+ * - Creates `Unit_TypescriptLib` instance
+ * - Configures output directory from `publishConfig.directory`
+ * - Sets hot reload flag from `unitConfig.hasSelfHotReload`
+ * - Detects custom ESLint/TSConfig files
+ *
+ * **Usage**: Automatically registered by `BuildAndInstall.prepareUnitsMapper()`.
+ */
 export class UnitMapper_NodeLib_Class extends UnitMapper_Node {
     static tsValidator_NodeProject = {
         type: tsValidateValue(['typescript-lib']),
@@ -10,6 +26,13 @@ export class UnitMapper_NodeLib_Class extends UnitMapper_Node {
     constructor() {
         super(UnitMapper_NodeLib_Class.tsValidator_NodeProject);
     }
+    /**
+     * Creates a Unit_TypescriptLib instance from resolved context.
+     *
+     * @param context - Resolved node unit context
+     * @returns Unit_TypescriptLib instance
+     * @throws BadImplementationException if publishConfig.directory is missing
+     */
     async resolveNodeUnit(context) {
         const outputDir = context.packageJson.publishConfig?.directory;
         if (!outputDir)

package/{v3/UnitsMapper → units/discovery}/resolvers/UnitMapper_NodeProject.d.ts

@@ -1,5 +1,20 @@
-import { Unit_NodeProject } from '../../units/index.js';
+import { Unit_NodeProject } from '../../implementations/Unit_NodeProject.js';
 import { UnitMapper_Node, UnitMapper_NodeContext } from './UnitMapper_Node.js';
+/**
+ * Mapper for discovering root NodeProject unit.
+ *
+ * **Discovery Criteria**:
+ * - Must have `package.json` with `unitConfig.type === 'node-project'`
+ * - Typically the monorepo root
+ *
+ * **Unit Creation**:
+ * - Creates `Unit_NodeProject` instance
+ * - Marks as root and top-level app
+ * - Enables hot reload
+ *
+ * **Usage**: Automatically registered by `BuildAndInstall.prepareUnitsMapper()`.
+ * There should typically be only one NodeProject unit per workspace.
+ */
 export declare class UnitMapper_NodeProject_Class extends UnitMapper_Node<Unit_NodeProject> {
     static tsValidator_NodeProject: {
         label: import("@nu-art/ts-common").Validator<string>;
@@ -9,6 +24,12 @@ export declare class UnitMapper_NodeProject_Class extends UnitMapper_Node<Unit_N
         type: import("@nu-art/ts-common").Validator<any>;
     };
     constructor();
+    /**
+     * Creates a Unit_NodeProject instance from resolved context.
+     *
+     * @param context - Resolved node unit context
+     * @returns Unit_NodeProject instance
+     */
     protected resolveNodeUnit(context: UnitMapper_NodeContext): Promise<Unit_NodeProject<{
         isTopLevelApp: true;
         isRoot: true;

package/{v3/UnitsMapper → units/discovery}/resolvers/UnitMapper_NodeProject.js

@@ -1,6 +1,21 @@
-import { Unit_NodeProject } from '../../units/index.js';
+import { Unit_NodeProject } from '../../implementations/Unit_NodeProject.js';
 import { tsValidateValue } from '@nu-art/ts-common';
 import { UnitMapper_Node } from './UnitMapper_Node.js';
+/**
+ * Mapper for discovering root NodeProject unit.
+ *
+ * **Discovery Criteria**:
+ * - Must have `package.json` with `unitConfig.type === 'node-project'`
+ * - Typically the monorepo root
+ *
+ * **Unit Creation**:
+ * - Creates `Unit_NodeProject` instance
+ * - Marks as root and top-level app
+ * - Enables hot reload
+ *
+ * **Usage**: Automatically registered by `BuildAndInstall.prepareUnitsMapper()`.
+ * There should typically be only one NodeProject unit per workspace.
+ */
 export class UnitMapper_NodeProject_Class extends UnitMapper_Node {
     static tsValidator_NodeProject = {
         type: tsValidateValue(['node-project']),
@@ -9,6 +24,12 @@ export class UnitMapper_NodeProject_Class extends UnitMapper_Node {
     constructor() {
         super(UnitMapper_NodeProject_Class.tsValidator_NodeProject);
     }
+    /**
+     * Creates a Unit_NodeProject instance from resolved context.
+     *
+     * @param context - Resolved node unit context
+     * @returns Unit_NodeProject instance
+     */
     async resolveNodeUnit(context) {
         return new Unit_NodeProject({
             ...context.baseConfig,

package/units/discovery/types.js

@@ -0,0 +1 @@
+export {};

package/units/implementations/Unit_NodeProject.d.ts

@@ -0,0 +1,59 @@
+import { UnitPhaseImplementor } from '../../core/types.js';
+import { StringMap } from '@nu-art/ts-common/utils/types';
+import { Unit_PackageJson, Unit_PackageJson_Config } from './Unit_PackageJson.js';
+import { ProjectUnit } from '../base/ProjectUnit.js';
+import { Phase_Install, Phase_IndicesMcpServer, Phase_PostPublish, Phase_Watch } from '../../phases/definitions/index.js';
+/**
+ * Configuration for NodeProject (root project unit).
+ */
+type Unit_TypescriptProject_Config = Unit_PackageJson_Config & {
+    globalPackages?: StringMap;
+    isRoot: true;
+};
+/**
+ * Root project unit representing the entire monorepo/workspace.
+ *
+ * **Key Responsibilities**:
+ * - Manages child units (all packages in workspace)
+ * - Handles workspace-level operations (install, watch)
+ * - Creates PNPM workspace configuration
+ * - Manages file watching for hot reload
+ *
+ * **Phases Implemented**:
+ * - `install()`: Installs all packages using PNPM workspace
+ * - `watch()`: Watches file changes and triggers incremental compilation
+ * - `postPublish()`: Post-publish operations
+ *
+ * **Watch Mode**:
+ * - Watches TypeScript, SCSS, JSON, SVG files in all child units
+ * - Uses chokidar for file watching
+ * - Debounces changes and compiles affected units in dependency order
+ * - Supports hot reload for units with `hasSelfHotReload` flag
+ *
+ * **Workspace Management**:
+ * - Creates `pnpm-workspace.yaml` with all child unit paths
+ * - Manages global packages installation
+ * - Handles dependency tree for watch compilation
+ */
+export declare class Unit_NodeProject<C extends Unit_TypescriptProject_Config = Unit_TypescriptProject_Config> extends Unit_PackageJson<C> implements UnitPhaseImplementor<[Phase_Install, Phase_Watch, Phase_PostPublish, Phase_IndicesMcpServer]> {
+    private watcher?;
+    readonly innerUnits: Unit_PackageJson[];
+    private readonly suffixesToWatch;
+    constructor(config: Unit_NodeProject<C>['config']);
+    protected deriveDistDependencies(): StringMap;
+    assignUnit(units: ProjectUnit[]): void;
+    /**
+     * Resolve all paths to watch in all project libs
+     * @private
+     * @returns string[]
+     */
+    private prepareWatchPaths;
+    stopWatch(): Promise<void | undefined>;
+    private findUnit;
+    install(): Promise<void>;
+    watch(timeout?: number, maxTimeout?: number): Promise<void>;
+    purge(): Promise<void>;
+    postPublish(): Promise<void>;
+    indicesMcpServer(): Promise<void>;
+}
+export {};

package/{v3/units → units/implementations}/Unit_NodeProject.js

@@ -6,13 +6,39 @@ import { Commando_PNPM } from '@nu-art/commando/shell/plugins/pnpm';
 import { PNPM } from '@nu-art/commando/shell/services/pnpm';
 import { Unit_PackageJson } from './Unit_PackageJson.js';
 import { resolve } from 'path';
-import { PhaseManager } from '../PhaseManager.js';
-import { phase_CompileWatch } from '../phase/index.js';
-import { UnitsDependencyMapper } from '../UnitsDependencyMapper/UnitsDependencyMapper.js';
+import { PhaseManager } from '../../phases/PhaseManager.js';
+import { phase_CompileWatch } from '../../phases/definitions/index.js';
+import { UnitsDependencyMapper } from '../../dependencies/UnitsDependencyMapper.js';
 import { CommandoException } from '@nu-art/commando/shell/core/CliError';
-import { CONST_PNPM_LOCK, CONST_PNPM_WORKSPACE } from '../../core/consts.js';
-import { RunningStatusHandler } from '../RunningStatusHandler.js';
+import { CONST_PNPM_LOCK, CONST_PNPM_WORKSPACE } from '../../config/consts.js';
+import { RunningStatusHandler } from '../../runtime/RunningStatusHandler.js';
 import { FileSystemUtils } from '@nu-art/ts-common/utils/FileSystemUtils';
+import { IndicesMcpServer } from '../../exports/IndicesMcpServer.js';
+/**
+ * Root project unit representing the entire monorepo/workspace.
+ *
+ * **Key Responsibilities**:
+ * - Manages child units (all packages in workspace)
+ * - Handles workspace-level operations (install, watch)
+ * - Creates PNPM workspace configuration
+ * - Manages file watching for hot reload
+ *
+ * **Phases Implemented**:
+ * - `install()`: Installs all packages using PNPM workspace
+ * - `watch()`: Watches file changes and triggers incremental compilation
+ * - `postPublish()`: Post-publish operations
+ *
+ * **Watch Mode**:
+ * - Watches TypeScript, SCSS, JSON, SVG files in all child units
+ * - Uses chokidar for file watching
+ * - Debounces changes and compiles affected units in dependency order
+ * - Supports hot reload for units with `hasSelfHotReload` flag
+ *
+ * **Workspace Management**:
+ * - Creates `pnpm-workspace.yaml` with all child unit paths
+ * - Manages global packages installation
+ * - Handles dependency tree for watch compilation
+ */
 export class Unit_NodeProject extends Unit_PackageJson {
     watcher;
     innerUnits = [];
@@ -162,7 +188,8 @@ export class Unit_NodeProject extends Unit_PackageJson {
                     noBuild: false,
                     continue: false
                 };
-                const phaseManager = new PhaseManager(new RunningStatusHandler(this.config.fullPath, watchRuntimeParams).isolate(), [[phase_CompileWatch]], unitDependencyTree);
+                const activeUnitKeys = this.runtimeContext.childUnits.map(unit => unit.config.key);
+                const phaseManager = new PhaseManager(new RunningStatusHandler(this.config.fullPath, watchRuntimeParams).isolate(), [[phase_CompileWatch]], unitDependencyTree, activeUnitKeys, activeUnitKeys);
                 // @ts-ignore
                 phaseManager.setTag('PhaseManager-Watcher');
                 const executionPlan = await phaseManager.calculateExecutionSteps();
@@ -240,4 +267,38 @@ export class Unit_NodeProject extends Unit_PackageJson {
     }
     async postPublish() {
     }
+    async indicesMcpServer() {
+        this.setStatus('Starting Export Indices MCP Server', 'start');
+        const projectRoot = this.config.fullPath;
+        const port = this.runtimeContext.runtimeParams.indicesMcpPort || 3001;
+        // Get active TypeScriptLib packages
+        const packages = this.innerUnits.filter(unit => unit.isInstanceOf(Unit_TypescriptLib));
+        if (packages.length === 0) {
+            this.logWarning('No TypeScriptLib packages found. MCP server will have no packages to expose.');
+        }
+        const server = new IndicesMcpServer(port, projectRoot, packages);
+        // Handle graceful shutdown
+        const shutdown = async () => {
+            this.logInfo('Shutting down Export Indices MCP Server...');
+            await server.stop();
+            process.exit(0);
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+        try {
+            await server.start();
+            this.setStatus('Export Indices MCP Server running', 'end');
+            this.logInfo(`Export Indices MCP Server is running on http://localhost:${port}`);
+            this.logInfo('Press Ctrl+C to stop the server');
+            // Keep process alive - return a promise that never resolves
+            return new Promise(() => {
+                // This promise never resolves, keeping the process alive
+            });
+        }
+        catch (error) {
+            this.logError('Failed to start Export Indices MCP Server:', error);
+            this.setStatus('Export Indices MCP Server failed', 'end');
+            throw error;
+        }
+    }
 }

package/units/implementations/Unit_PackageJson.d.ts

@@ -0,0 +1,56 @@
+import { StringMap } from '@nu-art/ts-common';
+import { UnitPhaseImplementor } from '../../core/types.js';
+import { Config_ProjectUnit, ProjectUnit } from '../base/ProjectUnit.js';
+import { TS_PackageJSON } from '../discovery/types.js';
+import { Phase_Prepare, Phase_Purge } from '../../phases/definitions/index.js';
+/**
+ * Configuration for PackageJson units (units with package.json).
+ */
+export type Unit_PackageJson_Config = Config_ProjectUnit & {
+    packageJson: TS_PackageJSON;
+};
+/**
+ * Base class for all units that have a package.json file.
+ *
+ * **Key Responsibilities**:
+ * - Manages package.json template transformation
+ * - Handles dependency derivation (lib and dist dependencies)
+ * - Implements prepare and purge phases
+ *
+ * **Dependency Management**:
+ * - `deriveLibDependencies()`: Creates workspace dependencies for development
+ * - `deriveDistDependencies()`: Creates versioned dependencies for distribution
+ *
+ * **Template System**: Uses FileSystemUtils to transform package.json templates
+ * with runtime parameters (THUNDERSTORM_VERSION, __ENV__, etc.).
+ *
+ * **Phases Implemented**:
+ * - `prepare()`: Generates package.json from template with resolved dependencies
+ * - `purge()`: Deletes package.json and node_modules
+ *
+ * **Base For**: Unit_NodeProject, Unit_TypescriptLib, Unit_FirebaseHosting, etc.
+ */
+export declare class Unit_PackageJson<C extends Unit_PackageJson_Config = Unit_PackageJson_Config> extends ProjectUnit<C> implements UnitPhaseImplementor<[Phase_Purge, Phase_Prepare]> {
+    constructor(config: C);
+    protected npmCommand(command: string): string;
+    protected deriveDistDependencies(): StringMap;
+    protected deriveLibDependencies(): StringMap;
+    /**
+     * Prepares package.json by generating it from template with resolved dependencies.
+     *
+     * **Process**:
+     * 1. Derives lib dependencies (workspace:* for development)
+     * 2. Transforms package.json template with params
+     * 3. Writes transformed package.json to disk
+     *
+     * **Template Params**: Includes THUNDERSTORM_VERSION, __ENV__, and child unit versions.
+     */
+    prepare(): Promise<void>;
+    /**
+     * Purges package.json and node_modules folder.
+     *
+     * Used by `--purge` flag to clean up before reinstall.
+     */
+    purge(): Promise<void>;
+    protected releasePorts(allPorts: string[]): Promise<void>;
+}