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

package/runtime/RunningStatusHandler.js

@@ -0,0 +1,153 @@
+import fs, { promises as _fs } from 'fs';
+import { __stringify, Logger } from '@nu-art/ts-common';
+/**
+ * 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 class RunningStatusHandler extends Logger {
+    isolated = false;
+    outputFolder;
+    // The completed units in the phase.. when running -con, these can be skipped
+    completedUnits = [];
+    runtimeParams;
+    startIndex = 0;
+    constructor(outputFolder, runtimeParams) {
+        super();
+        this.outputFolder = outputFolder;
+        this.runtimeParams = runtimeParams;
+    }
+    /**
+     * 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)
+     */
+    async init() {
+        if (!fs.existsSync(this.outputFolder))
+            await _fs.mkdir(this.outputFolder, { recursive: true });
+        if (this.runtimeParams.continue) {
+            const currentParams = this.runtimeParams;
+            this.startIndex = await this.load();
+            this.runtimeParams = Object.assign(currentParams, this.runtimeParams);
+        }
+    }
+    /**
+     * Enables isolation mode (skips saving state).
+     *
+     * Useful for tests or when state persistence is not desired.
+     *
+     * @returns This instance for chaining
+     */
+    isolate() {
+        this.isolated = true;
+        return this;
+    }
+    /**
+     * 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) {
+        return this.completedUnits.includes(unitKey);
+    }
+    /**
+     * Marks a unit as completed and saves state.
+     *
+     * Called after a unit successfully completes all its phases.
+     *
+     * @param unitKey - Unit key that completed
+     */
+    async onUnitCompleted(unitKey) {
+        this.logDebug(`On unit completed: ${unitKey}`);
+        this.completedUnits.push(unitKey);
+        await this.saveStatus();
+    }
+    /**
+     * Called when a step completes successfully.
+     *
+     * Clears completed units list for the next step.
+     */
+    async onStepEnded() {
+        this.logDebug(`On step ended successfully #${this.startIndex}`);
+        this.completedUnits = [];
+    }
+    /**
+     * Called when a step starts.
+     *
+     * Updates start index and saves state (unless isolated).
+     *
+     * @param index - Step index (0-based)
+     */
+    async onStepStarted(index) {
+        this.startIndex = index;
+        this.logDebug(`Setting execution index to #${this.startIndex}`);
+        await this.saveStatus();
+    }
+    /**
+     * 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.
+     */
+    async saveStatus() {
+        if (this.isolated)
+            return;
+        await _fs.writeFile(`${this.outputFolder}/running-status.json`, __stringify({
+            index: this.startIndex,
+            runtimeParams: this.runtimeParams,
+            completedUnits: this.completedUnits
+        }, true));
+    }
+    /**
+     * 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
+     */
+    async load() {
+        try {
+            const data = JSON.parse(await _fs.readFile(`${this.outputFolder}/running-status.json`, { encoding: 'utf-8' }));
+            this.startIndex = data.index;
+            this.completedUnits = data.completedUnits ?? [];
+            this.runtimeParams = data.runtimeParams;
+            return data.index;
+        }
+        catch (e) {
+            this.logError('Failed reading running status, using initial status', e);
+            return;
+        }
+    }
+}

package/runtime/types.d.ts

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

package/runtime/types.js

@@ -0,0 +1,2 @@
+// Runtime types will be defined here if needed
+export {};

package/{defaults → templates}/consts.d.ts

@@ -11,6 +11,15 @@ export declare const Const_FirebaseDefaultsKeyToFile: {
     [k in typeof Const_FirebaseConfigKeys[number]]: string;
 };
 export declare const Default_Files: ProjectConfig_DefaultFileRoutes;
+/**
+ * Template file paths for Firebase Functions container builds.
+ * These are used when no custom templates are specified in baiConfig.
+ */
+export declare const FunctionBuildTemplateFiles: {
+    dockerfile: string;
+    cloudbuildYaml: string;
+    serviceYaml: string;
+};
 export declare const Default_OutputFiles: {
     output: string;
     outputLogs: string;

package/{defaults → templates}/consts.js

@@ -3,8 +3,9 @@ import { dirname } from 'node:path';
 // ESM-safe replacements for __filename/__dirname
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const CONST_FirebaseConfig = `${__dirname}/.firebase_config`;
-const CONST_BackendProxy = `${__dirname}/backend-proxy`;
+const CONST_FirebaseConfig = `${__dirname}/firebase/config`;
+const CONST_FirebaseFunctions = `${__dirname}/firebase/functions`;
+const CONST_BackendProxy = `${__dirname}/backend/proxy`;
 export const Const_FirebaseConfigKeys = [
     'databaseRules',
     'firestoreIndexesRules',
@@ -28,6 +29,15 @@ export const Default_Files = {
         proxy: `${CONST_BackendProxy}/proxy._ts`
     }
 };
+/**
+ * Template file paths for Firebase Functions container builds.
+ * These are used when no custom templates are specified in baiConfig.
+ */
+export const FunctionBuildTemplateFiles = {
+    dockerfile: `${CONST_FirebaseFunctions}/dockerfile`,
+    cloudbuildYaml: `${CONST_FirebaseFunctions}/cloudbuild.yaml`,
+    serviceYaml: `${CONST_FirebaseFunctions}/service.yaml`,
+};
 const Default_OutputPath = './.trash';
 export const Default_OutputFiles = {
     output: Default_OutputPath,

package/templates/firebase/functions/cloudbuild.yaml

@@ -0,0 +1,17 @@
+steps:
+  - name: 'gcr.io/cloud-builders/docker'
+    args:
+      - 'build'
+      - '--platform=linux/amd64'
+      - '-t'
+      - '{{IMAGE_REFERENCE}}'
+      - '-t'
+      - '{{IMAGE_REFERENCE_LATEST}}'
+      - '-f'
+      - '{{DOCKERFILE_PATH}}'
+{{LABELS}}
+      - '.'
+images:
+  - '{{IMAGE_REFERENCE}}'
+  - '{{IMAGE_REFERENCE_LATEST}}'
+

package/templates/firebase/functions/dockerfile

@@ -0,0 +1,19 @@
+FROM node:22
+WORKDIR /workspace/dist
+
+# Copy dist folder (which contains package.json and all compiled code)
+COPY dist/ ./
+
+# Install dependencies including functions-framework
+RUN npm install --production && \
+    npm install -g @google-cloud/functions-framework
+
+# Expose the port that Cloud Run will use
+EXPOSE 8080
+
+# Use functions-framework to run the function
+# FUNCTION_TARGET environment variable (set by deployment) specifies which exported function to invoke
+# PORT is automatically set by Cloud Run (default 8080)
+# The framework will load index.js (since we're already in the dist directory)
+CMD ["functions-framework", "--source=index.js"]
+

package/templates/firebase/functions/service.yaml

@@ -0,0 +1,49 @@
+HttpSeapiVersion: serving.knative.dev/v1
+kind: Service
+metadata:
+  name: {{SERVICE_NAME}}
+  labels:
+    goog-cloudfunctions-runtime: nodejs22
+    cloud.googleapis.com/location: {{REGION}}
+    goog-managed-by: cloudfunctions
+  annotations:
+    serving.knative.dev/creator: service-{{RUNTIME_PROJECT_ID}}@gcf-admin-robot.iam.gserviceaccount.com
+    run.googleapis.com/client-name: cli-firebase
+    cloudfunctions.googleapis.com/function-id: {{FUNCTION_NAME}}
+    run.googleapis.com/ingress: all
+    run.googleapis.com/ingress-status: all
+spec:
+  template:
+    metadata:
+      labels: {}
+      annotations:
+        autoscaling.knative.dev/maxScale: '{{MAX_INSTANCES}}'
+        autoscaling.knative.dev/minScale: '{{MIN_INSTANCES}}'
+        run.googleapis.com/startup-cpu-boost: 'true'
+        cloudfunctions.googleapis.com/trigger-type: {{TRIGGER_TYPE}}
+    spec:
+      containerConcurrency: {{CONCURRENCY}}
+      timeoutSeconds: {{TIMEOUT}}
+{{SERVICE_ACCOUNT}}
+      containers:
+      - name: worker
+        image: {{IMAGE_REFERENCE}}
+        ports:
+        - name: http1
+          containerPort: 8080
+        env:
+{{ENV_VARS}}
+        resources:
+          limits:
+            cpu: '{{CPU}}'
+            memory: {{MEMORY}}
+        startupProbe:
+          timeoutSeconds: 240
+          periodSeconds: 240
+          failureThreshold: 1
+          tcpSocket:
+            port: 8080
+  traffic:
+  - percent: 100
+    latestRevision: true
+

package/{v3/units → units/base}/BaseUnit.d.ts

@@ -3,14 +3,23 @@ import { CommandoInteractive } from '@nu-art/commando/shell/index';
 import { BaseCommando } from '@nu-art/commando/shell/core/BaseCommando';
 import { MergeTypes } from '@nu-art/commando/shell/core/class-merger';
 import { Commando_Basic } from '@nu-art/commando/shell/plugins/basic';
-import { BAI_Config } from '../../core/types/index.js';
-import { UnitsDependencyMapper } from '../UnitsDependencyMapper/UnitsDependencyMapper.js';
-import { BaiParams } from '../../core/params/params.js';
+import { BAI_Config } from '../../config/types/index.js';
+import { UnitsDependencyMapper } from '../../dependencies/UnitsDependencyMapper.js';
+import { BaiParams } from '../../core/params.js';
+import { Workspace } from '../../workspace/Workspace.js';
+/**
+ * Base configuration for all units.
+ */
 export type BaseUnit_Config = {
     key: string;
     label: string;
     isTopLevelApp?: boolean;
 };
+/**
+ * Runtime context provided to all units during execution.
+ *
+ * Contains version, config, dependency mapper, runtime params, and workspace reference.
+ */
 export type UnitRuntimeContext = {
     version: string;
     baiConfig: Readonly<BAI_Config>;
@@ -18,7 +27,30 @@ export type UnitRuntimeContext = {
     unitsResolver: <Class extends BaseUnit>(keys: string[], className: Constructor<Class>) => Class[];
     runtimeParams: BaiParams;
     globalOutputFolder: string;
+    workspace?: Workspace;
 };
+/**
+ * Base class for all units in the build system.
+ *
+ * **Unit Lifecycle**:
+ * 1. **Discovery**: Units are discovered by UnitsMapper from file system
+ * 2. **Initialization**: Constructor sets up config and logging
+ * 3. **Context Setup**: `setupRuntimeContext()` provides runtime information
+ * 4. **Phase Execution**: Phases call unit methods (e.g., `compile()`, `test()`)
+ * 5. **Termination**: `kill()` stops all running processes
+ *
+ * **Key Features**:
+ * - **Commando Integration**: Allocates Commando instances for shell commands
+ * - **Process Management**: Tracks and kills subprocesses on termination
+ * - **Logging**: Buffered logging with status tracking
+ * - **Time Tracking**: Measures operation duration
+ *
+ * **Phase Methods**: Units implement phase methods (e.g., `prepare()`, `compile()`, `test()`)
+ * that are called by PhaseManager. Methods are discovered via reflection.
+ *
+ * **Status Tracking**: Units track their status ('Pending Initialization', 'Running', etc.)
+ * for monitoring and debugging.
+ */
 export declare abstract class BaseUnit<C extends BaseUnit_Config = BaseUnit_Config, RT_Context extends UnitRuntimeContext = UnitRuntimeContext> extends Logger {
     readonly config: Readonly<C>;
     private unitStatus;

package/{v3/units → units/base}/BaseUnit.js

@@ -1,6 +1,27 @@
 import { _logger_finalDate, _logger_getPrefix, _logger_timezoneOffset, BeLogged, exists, lastElement, LogClient_MemBuffer, Logger, LogLevel, removeItemFromArray, timeCounter } from '@nu-art/ts-common';
-import { dispatcher_UnitStatusChange } from '../../old/PhaseRunnerDispatcher.js';
 import { CommandoPool } from '@nu-art/commando/shell/core/CommandoPool';
+/**
+ * Base class for all units in the build system.
+ *
+ * **Unit Lifecycle**:
+ * 1. **Discovery**: Units are discovered by UnitsMapper from file system
+ * 2. **Initialization**: Constructor sets up config and logging
+ * 3. **Context Setup**: `setupRuntimeContext()` provides runtime information
+ * 4. **Phase Execution**: Phases call unit methods (e.g., `compile()`, `test()`)
+ * 5. **Termination**: `kill()` stops all running processes
+ *
+ * **Key Features**:
+ * - **Commando Integration**: Allocates Commando instances for shell commands
+ * - **Process Management**: Tracks and kills subprocesses on termination
+ * - **Logging**: Buffered logging with status tracking
+ * - **Time Tracking**: Measures operation duration
+ *
+ * **Phase Methods**: Units implement phase methods (e.g., `prepare()`, `compile()`, `test()`)
+ * that are called by PhaseManager. Methods are discovered via reflection.
+ *
+ * **Status Tracking**: Units track their status ('Pending Initialization', 'Running', etc.)
+ * for monitoring and debugging.
+ */
 export class BaseUnit extends Logger {
     config;
     unitStatus = 'Pending Initialization';
@@ -86,7 +107,6 @@ export class BaseUnit extends Logger {
             }
         this.log(logLevel, false, [`Unit status update: ${this.unitStatus} => ${status}${operationDuration}`]);
         this.unitStatus = `${status}${operationDuration}`;
-        dispatcher_UnitStatusChange.dispatch(this);
     }
     addToClassStack = (cls) => {
         this.classStack.push(cls.name);

package/units/base/ProjectUnit.d.ts

@@ -0,0 +1,32 @@
+import { StringMap } from '@nu-art/ts-common';
+import { BaseUnit, BaseUnit_Config, UnitRuntimeContext } from './BaseUnit.js';
+export type Config_ProjectUnit = BaseUnit_Config & {
+    relativePath: string;
+    fullPath: string;
+    dependencies: StringMap;
+};
+export type ProjectUnit_RuntimeContext = UnitRuntimeContext & {
+    parentUnit: ProjectUnit<any>;
+    childUnits: ProjectUnit[];
+};
+/**
+ * Abstract base class for project units (packages/apps in the workspace).
+ *
+ * **Project Units vs Base Units**:
+ * - **Project Units**: Have file paths, dependencies, and participate in dependency resolution
+ * - **Base Units**: Generic units without file system context
+ *
+ * **Key Properties**:
+ * - `relativePath`: Path relative to project root
+ * - `fullPath`: Absolute path to unit directory
+ * - `dependencies`: Map of dependency keys (for dependency resolution)
+ *
+ * **Runtime Context**: ProjectUnits receive `ProjectUnit_RuntimeContext` which includes:
+ * - `parentUnit`: Root NodeProject unit
+ * - `childUnits`: All project units in workspace
+ *
+ * **Examples**: Unit_NodeProject, Unit_TypescriptLib, Unit_FirebaseHostingApp
+ */
+export declare abstract class ProjectUnit<C extends Config_ProjectUnit = Config_ProjectUnit> extends BaseUnit<C, ProjectUnit_RuntimeContext> {
+    constructor(config: C);
+}

package/units/base/ProjectUnit.js

@@ -0,0 +1,25 @@
+import { BaseUnit } from './BaseUnit.js';
+/**
+ * Abstract base class for project units (packages/apps in the workspace).
+ *
+ * **Project Units vs Base Units**:
+ * - **Project Units**: Have file paths, dependencies, and participate in dependency resolution
+ * - **Base Units**: Generic units without file system context
+ *
+ * **Key Properties**:
+ * - `relativePath`: Path relative to project root
+ * - `fullPath`: Absolute path to unit directory
+ * - `dependencies`: Map of dependency keys (for dependency resolution)
+ *
+ * **Runtime Context**: ProjectUnits receive `ProjectUnit_RuntimeContext` which includes:
+ * - `parentUnit`: Root NodeProject unit
+ * - `childUnits`: All project units in workspace
+ *
+ * **Examples**: Unit_NodeProject, Unit_TypescriptLib, Unit_FirebaseHostingApp
+ */
+export class ProjectUnit extends BaseUnit {
+    constructor(config) {
+        super(config);
+        this.addToClassStack(ProjectUnit);
+    }
+}

package/units/base/types.js

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

package/units/discovery/UnitsMapper.d.ts

@@ -0,0 +1,69 @@
+import { BaseUnit, ProjectUnit } from '../index.js';
+import { Logger } from '@nu-art/ts-common';
+import { UnitMapper_Base } from './resolvers/UnitMapper_Base.js';
+import { BaiParams } from '../../core/params.js';
+/**
+ * Recursively scans workspace and discovers units using resolution rules.
+ *
+ * **Discovery Process**:
+ * 1. Starts at project root path
+ * 2. Applies resolution rules in order (first match wins)
+ * 3. If unit found and not root, stops recursion (unit is a leaf)
+ * 4. If unit is root, continues scanning subdirectories
+ * 5. Skips `node_modules` and hidden directories (`.git`, `.vscode`, etc.)
+ *
+ * **Resolution Rules**:
+ * - Rules are added via `addRules()` (e.g., UnitMapper_NodeLib, UnitMapper_FirebaseFunction)
+ * - Each rule checks if a path matches its criteria (package.json, firebase.json, etc.)
+ * - Rules can be configured with runtime params
+ *
+ * **Unit Types**:
+ * - **Root Units**: Continue scanning subdirectories (e.g., monorepo root)
+ * - **Leaf Units**: Stop recursion (e.g., individual packages)
+ *
+ * **Filtering**: Automatically skips:
+ * - `node_modules` directories
+ * - Hidden directories (starting with `.`)
+ *
+ * **Usage**: Called by `Workspace.scanUnits()` to discover all units in workspace.
+ */
+export declare class UnitsMapper extends Logger {
+    private rules;
+    /**
+     * @param path - will always be a directory
+     * @param projectRoot - The path to the project root
+     * @param units - The project units derived from the file system
+     */
+    resolveUnits(path: string, projectRoot?: string, units?: BaseUnit<any>[]): Promise<BaseUnit<any, import("../index.js").UnitRuntimeContext>[]>;
+    /**
+     * Adds unit resolution rules.
+     *
+     * Rules are tried in order (first match wins). Common rules:
+     * - `UnitMapper_NodeProject`: Root project unit
+     * - `UnitMapper_NodeLib`: TypeScript libraries
+     * - `UnitMapper_FirebaseHosting`: Firebase hosting apps
+     * - `UnitMapper_FirebaseFunction`: Firebase functions
+     *
+     * @param rules - Unit mapper rules to add
+     * @returns This instance for chaining
+     */
+    addRules<T extends BaseUnit<any>>(...rules: UnitMapper_Base<T>[]): this;
+    /**
+     * Sets runtime params on all rules.
+     *
+     * Rules can use runtime params to filter or configure resolution behavior.
+     *
+     * @param runtimeParams - Runtime parameters
+     * @returns This instance for chaining
+     */
+    setRuntimeParams(runtimeParams: BaiParams): this;
+    /**
+     * Validates that all units have unique keys.
+     *
+     * Throws `BadImplementationException` if duplicate keys found.
+     *
+     * @param units - Units to validate
+     * @throws BadImplementationException if duplicate keys found
+     */
+    assertUniqueKeys(units: ProjectUnit[]): void;
+}

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

@@ -1,9 +1,29 @@
 import { promises as fs } from 'fs';
 import { BadImplementationException, Logger } from '@nu-art/ts-common';
 /**
- * This class will receive a path and will map the workspace packages and libs
+ * Recursively scans workspace and discovers units using resolution rules.
  *
- * A lib will have rules to infer it, mainly from the package.json but also from existing files in the context of the node lib
+ * **Discovery Process**:
+ * 1. Starts at project root path
+ * 2. Applies resolution rules in order (first match wins)
+ * 3. If unit found and not root, stops recursion (unit is a leaf)
+ * 4. If unit is root, continues scanning subdirectories
+ * 5. Skips `node_modules` and hidden directories (`.git`, `.vscode`, etc.)
+ *
+ * **Resolution Rules**:
+ * - Rules are added via `addRules()` (e.g., UnitMapper_NodeLib, UnitMapper_FirebaseFunction)
+ * - Each rule checks if a path matches its criteria (package.json, firebase.json, etc.)
+ * - Rules can be configured with runtime params
+ *
+ * **Unit Types**:
+ * - **Root Units**: Continue scanning subdirectories (e.g., monorepo root)
+ * - **Leaf Units**: Stop recursion (e.g., individual packages)
+ *
+ * **Filtering**: Automatically skips:
+ * - `node_modules` directories
+ * - Hidden directories (starting with `.`)
+ *
+ * **Usage**: Called by `Workspace.scanUnits()` to discover all units in workspace.
  */
 export class UnitsMapper extends Logger {
     rules = [];
@@ -20,7 +40,7 @@ export class UnitsMapper extends Logger {
             unit = await rule.resolveUnit(path, projectRoot);
             if (!unit)
                 continue;
-            this.logDebug(`Found unit ${unit.config.key} at path ${path}`);
+            this.logVerbose(`Found unit ${unit.config.key} at path ${path}`);
             units.push(unit);
             if (!unit.config.isRoot)
                 return units;
@@ -38,14 +58,42 @@ export class UnitsMapper extends Logger {
         }
         return units;
     }
+    /**
+     * Adds unit resolution rules.
+     *
+     * Rules are tried in order (first match wins). Common rules:
+     * - `UnitMapper_NodeProject`: Root project unit
+     * - `UnitMapper_NodeLib`: TypeScript libraries
+     * - `UnitMapper_FirebaseHosting`: Firebase hosting apps
+     * - `UnitMapper_FirebaseFunction`: Firebase functions
+     *
+     * @param rules - Unit mapper rules to add
+     * @returns This instance for chaining
+     */
     addRules(...rules) {
         this.rules.push(...rules);
         return this;
     }
+    /**
+     * Sets runtime params on all rules.
+     *
+     * Rules can use runtime params to filter or configure resolution behavior.
+     *
+     * @param runtimeParams - Runtime parameters
+     * @returns This instance for chaining
+     */
     setRuntimeParams(runtimeParams) {
         this.rules.forEach(rule => rule.setRuntimeParams(runtimeParams));
         return this;
     }
+    /**
+     * Validates that all units have unique keys.
+     *
+     * Throws `BadImplementationException` if duplicate keys found.
+     *
+     * @param units - Units to validate
+     * @throws BadImplementationException if duplicate keys found
+     */
     assertUniqueKeys(units) {
         const keyToUnit = {};
         for (const unit of units) {

package/units/discovery/resolvers/UnitMapper_Base.d.ts

@@ -0,0 +1,65 @@
+import { AbsolutePath, Logger, RelativePath, StringMap, TypeValidator } from '@nu-art/ts-common';
+import { BaseUnit } from '../../index.js';
+import { BAI_Config } from '../../../config/types/index.js';
+import { BaiParams } from '../../../core/params.js';
+export type BaseUnitConfig = {
+    fullPath: AbsolutePath;
+    relativePath: RelativePath;
+    label: string;
+    key: string;
+    dependencies: StringMap;
+};
+export type UnitConfigJSON_Base = {
+    type: string;
+};
+/**
+ * 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 declare abstract class UnitMapper_Base<T extends BaseUnit<any>, ConfigJSON extends UnitConfigJSON_Base = UnitConfigJSON_Base> extends Logger {
+    protected validator: TypeValidator<ConfigJSON>;
+    protected baiConfig: BAI_Config;
+    protected runtimeParams: BaiParams;
+    protected constructor(validator: TypeValidator<ConfigJSON>);
+    /**
+     * Sets runtime parameters for the mapper.
+     *
+     * Called by UnitsMapper to provide runtime context.
+     */
+    setRuntimeParams(runtimeParams: BaiParams): void;
+    /**
+     * Sets BAI configuration for the mapper.
+     *
+     * Called by UnitsMapper to provide configuration context.
+     */
+    setConfig(config: BAI_Config): void;
+    /**
+     * Resolves a unit from a directory path.
+     *
+     * **Behavior**:
+     * - Checks if path matches this mapper's criteria
+     * - If match, creates and returns unit instance
+     * - If no match, returns undefined
+     *
+     * @param path - Directory path to check
+     * @param root - Project root path
+     * @returns Promise resolving to unit instance or undefined
+     */
+    abstract resolveUnit(path: string, root: string): Promise<T | undefined>;
+}