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

package/core/params.js

@@ -0,0 +1,441 @@
+import { BadImplementationException, tsValidate, tsValidateRegexp } from '@nu-art/ts-common';
+export const BaiParam_AllUnits = {
+    keys: ['--all-units', '-all'],
+    keyName: 'allUnits',
+    type: 'boolean',
+    group: 'Build',
+    description: 'By default only top level and their dependencies are included, using this flag will include ALL the units'
+};
+export const BaiParam_DependencyTree = {
+    keys: ['--dependency-tree', '-dt'],
+    keyName: 'dependencyTree',
+    type: 'boolean',
+    group: 'General',
+    description: 'Will print the projects packages dependencies tree into the .trash folder'
+};
+export const BaiParam_SetEnv = {
+    keys: ['--set-env', '-se'],
+    keyName: 'environment',
+    type: 'string',
+    group: 'Build',
+    initialValue: 'local',
+    description: 'Will set the .config-${environment}.json as the current .config.json and prepare it as base 64 for local usage \ninput required: envName(string)'
+};
+export const BaiParam_Install = {
+    keys: ['--install', '-i'],
+    keyName: 'install',
+    type: 'boolean',
+    group: 'Build',
+    description: 'Will run \'pnpm install\' on entire project and will install global packages'
+};
+export const BaiParam_Clean = {
+    keys: ['--clean', '-c'],
+    keyName: 'clean',
+    type: 'boolean',
+    group: 'Clean',
+    description: 'Will delete the output(dist) & test output(dist-test) folders in all project packages'
+};
+export const BaiParam_Purge = {
+    keys: ['--purge', '-p'],
+    dependencies: [{ param: BaiParam_Clean, value: true }, { param: BaiParam_Install, value: true }],
+    keyName: 'purge',
+    group: 'Clean',
+    type: 'boolean',
+    description: 'Will delete the node_modules folder in all project packages \nWill perform --clean --install'
+};
+export const BaiParam_Generate = {
+    keys: ['--generate', '-g'],
+    keyName: 'generate',
+    type: 'boolean',
+    group: 'Build',
+    description: 'Will generate sources in the apps if needed'
+};
+export const BaiParam_GenerateDocs = {
+    keys: ['--generate-docs', '-docs'],
+    keyName: 'generateDocs',
+    type: 'boolean',
+    group: 'Build',
+    description: 'Would generate ts-docs documentation'
+};
+export const BaiParam_NoBuild = {
+    keys: ['--no-build', '-nb'],
+    keyName: 'noBuild',
+    group: 'Build',
+    type: 'boolean',
+    description: 'Skip the build and link steps',
+};
+export const BaiParam_Prepare = {
+    keys: [],
+    keyName: 'prepare',
+    group: 'Build',
+    type: 'boolean',
+    initialValue: true,
+    description: '-- internal param --'
+};
+export const BaiParam_DryRun = {
+    keys: ['--dry-run', '-dry', '--dryrun'],
+    keyName: 'dryRun',
+    group: 'Other',
+    type: 'boolean',
+    description: 'Do not perform any phase impl, only log the process'
+};
+export const BaiParam_Lint = {
+    keys: ['--lint'],
+    keyName: 'lint',
+    type: 'boolean',
+    group: 'Build',
+    description: 'Run lint on all the project packages'
+};
+export const BaiParam_Watch = {
+    keys: ['--watch', '-w'],
+    keyName: 'watch',
+    type: 'boolean',
+    group: 'Build',
+    description: 'will build and listen for changes in the libraries',
+    dependencies: [{ param: BaiParam_NoBuild, value: true }, { param: BaiParam_Prepare, value: false }, { param: BaiParam_AllUnits, value: true }]
+};
+export const BaiParam_WatchBuildTree = {
+    keys: ['--watchBuildTree', '-wbt'],
+    keyName: 'watchBuildTree',
+    type: 'boolean',
+    group: 'Build',
+    description: 'Once watch triggers, will build the entire tree that depends on the libs that changed',
+    dependencies: [{ param: BaiParam_Watch, value: true }, { param: BaiParam_NoBuild, value: true }, { param: BaiParam_Prepare, value: false }]
+};
+export const BaiParam_continue = {
+    keys: ['--continue', '-con'],
+    keyName: 'continue',
+    type: 'boolean',
+    group: 'Build',
+    description: 'Will pick up where last build process failed',
+    dependencies: [{ param: BaiParam_Watch, value: false }]
+};
+export const BaiParam_Test = {
+    keys: ['--test', '-t'],
+    keyName: 'test',
+    type: 'boolean',
+    group: 'Test',
+    description: 'Run the tests in all the project packages',
+};
+export const TestTypes = ['pure', 'firebase', 'ui', 'mobile'];
+export const BaiParam_TestType = {
+    keys: ['--test-type', '-tt'],
+    keyName: 'testType',
+    type: 'string[]',
+    isArray: true,
+    group: 'Test',
+    options: TestTypes,
+    description: 'Run the tests in all the project packages',
+    dependencies: [{ param: BaiParam_Test, value: true }],
+};
+export const BaiParam_TestFile = {
+    keys: ['--test-file', '-tf'],
+    keyName: 'testFiles',
+    type: 'string[]',
+    isArray: true,
+    group: 'Test',
+    description: 'Run the specified test files',
+    dependencies: [{ param: BaiParam_Test, value: true }],
+};
+export const BaiParam_TestCase = {
+    keys: ['--test-case', '-tc'],
+    keyName: 'testCases',
+    type: 'string[]',
+    isArray: true,
+    group: 'Test',
+    description: 'Run only the specified test cases',
+    dependencies: [{ param: BaiParam_Test, value: true }],
+};
+export const BaiParam_TestDebugPort = {
+    keys: ['--test-debug', '-td'],
+    keyName: 'testDebugPort',
+    type: 'number',
+    group: 'Test',
+    defaultValue: 8010,
+    description: 'If provided will allow a debugger connection on the specified port, and will run the tests in watch mode',
+    dependencies: [{ param: BaiParam_Test, value: true }],
+};
+export const BaiParam_Launch = {
+    keys: ['--launch', '-l'],
+    keyName: 'launch',
+    type: 'boolean',
+    group: 'Apps',
+    description: 'Will perform the launch phast on packages that supports it. use the --use-package flag to filter out for specific packages'
+};
+export const BaiParam_DebugBackend = {
+    keys: ['--debug-backend', '-lbd'],
+    keyName: 'debugBackend',
+    type: 'boolean',
+    group: 'Apps',
+    description: 'Will add the app backend to the launch list - in debug mode'
+};
+export const BaiParam_Deploy = {
+    keys: ['--deploy', '-dep'],
+    keyName: 'deploy',
+    type: 'boolean',
+    group: 'Apps',
+    description: 'Will perform the deploy phast on packages that supports it. use the --use-package flag to filter out for specific packages',
+    dependencies: [
+        { param: BaiParam_Launch, value: false },
+        { param: BaiParam_Watch, value: false },
+        { param: BaiParam_WatchBuildTree, value: false },
+        { param: BaiParam_GenerateDocs, value: false },
+    ]
+};
+// Docker image tag validation: alphanumeric with dots, underscores, hyphens
+// Cannot start with period or hyphen, max 128 characters
+// Pattern: starts with alphanumeric, followed by 0-127 more alphanumeric/separator chars
+const imageTagRegex = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
+export const BaiParam_BuildPushImage = {
+    keys: ['--build-push-image', '-bpi'],
+    keyName: 'buildPushImage',
+    type: 'string',
+    group: 'Deployment',
+    description: `Build Docker container image and push to Artifact Registry. Usage: --build-push-image=<tag>`,
+    process: (value) => {
+        if (!value)
+            throw new BadImplementationException('Image tag is required. Use --build-push-image=<tag>');
+        tsValidate(value, tsValidateRegexp(imageTagRegex, true));
+        return value;
+    },
+};
+export const BaiParam_DeployImage = {
+    keys: ['--deploy-image', '-di'],
+    keyName: 'deployImage',
+    type: 'string',
+    group: 'Deployment',
+    description: 'Deploy container image from Artifact Registry to Firebase Functions. Usage: --deploy-image <tag>',
+    process: (value) => {
+        if (!value)
+            throw new BadImplementationException('Image tag is required. Use --deploy-image=<tag>');
+        tsValidate(value, tsValidateRegexp(imageTagRegex, true));
+        return value;
+    }
+};
+export const BaiParam_DeployFunction = {
+    keys: ['--deploy-function', '-df'],
+    keyName: 'deployFunction',
+    type: 'string',
+    group: 'Deployment',
+    description: 'Deploy a specific function by name. Usage: --deploy-function <functionName>',
+    process: (value) => {
+        if (!value)
+            throw new BadImplementationException('Function name is required. Use --deploy-function=<functionName>');
+        // Function name validation - just ensure it's a non-empty string
+        if (typeof value !== 'string' || value.trim().length === 0)
+            throw new BadImplementationException('Function name must be a non-empty string');
+        return value;
+    },
+};
+export const BaiParam_DeleteFunctions = {
+    keys: ['--delete-functions'],
+    keyName: 'deleteFunctions',
+    type: 'boolean',
+    group: 'Deployment',
+    description: 'Delete functions before deployment. Behavior depends on other flags.',
+};
+export const BaiParam_DeleteFunction = {
+    keys: ['--delete-function', '-delfn'],
+    keyName: 'deleteFunction',
+    type: 'string',
+    group: 'Deployment',
+    description: 'Delete a specific function by name before deployment. Usage: --delete-function=<functionName>',
+    process: (value) => {
+        if (!value)
+            throw new BadImplementationException('Function name is required. Use --delete-function=<functionName>');
+        // Function name validation - just ensure it's a non-empty string
+        if (typeof value !== 'string' || value.trim().length === 0)
+            throw new BadImplementationException('Function name must be a non-empty string');
+        return value;
+    },
+    dependencies: [{ param: BaiParam_DeleteFunctions, value: true }]
+};
+export const BaiParam_Debug = {
+    keys: ['--debug', '-d'],
+    keyName: 'debug',
+    group: 'Other',
+    type: 'boolean',
+    description: 'Will print the parameters the script is running with'
+};
+export const BaiParam_DebugLifecycle = {
+    keys: ['--debug-lifecycle', '-dl'],
+    keyName: 'debugLifecycle',
+    group: 'Other',
+    type: 'boolean',
+    description: 'Will only print the run config and die'
+};
+export const BaiParam_Verbose = {
+    keys: ['--verbose', '-v'],
+    keyName: 'verbose',
+    group: 'Other',
+    type: 'boolean',
+    description: 'Set log level to verbose'
+};
+export const BaiParam_QuickDeploy = {
+    keys: ['--quick-deploy', '-qd'],
+    keyName: 'quickDeploy',
+    type: 'boolean',
+    group: 'Other',
+    description: 'Will perform the deploy phase without other lifecycle options',
+    dependencies: [
+        ...BaiParam_Deploy.dependencies,
+        { param: BaiParam_Purge, value: false },
+        { param: BaiParam_Lint, value: false },
+        { param: BaiParam_Test, value: false },
+        { param: BaiParam_NoBuild, value: true },
+    ]
+};
+export const BaiParam_Publish = {
+    keys: ['--publish'],
+    keyName: 'publish',
+    type: 'string',
+    group: 'Other',
+    options: ['patch', 'minor', 'major'],
+    defaultValue: 'patch',
+    description: 'Will publish to NPM any package that is not marked as private in its __package.json   \nenum options: patch | minor | major \nDefault Param: patch',
+    process: (part) => part ?? 'patch'
+};
+export const BaiParam_UsePackage = {
+    keys: ['-up', '--use-packages'],
+    keyName: 'usePackage',
+    type: 'string[]',
+    group: 'Other',
+    description: 'Will specify units to process',
+    process: (value) => {
+        if (!value)
+            return [];
+        return value.split(',').map(str => str.trim());
+    },
+    dependencies: [{ param: BaiParam_AllUnits, value: true }]
+};
+export const BaiParam_BuildTree = {
+    keys: ['--build-tree', '-bt'],
+    keyName: 'buildTree',
+    type: 'boolean',
+    group: 'Build',
+    description: 'When used with -up, makes all transitive dependencies active (compile/test them too)',
+};
+export const BaiParam_Apps = {
+    keys: ['-app', '--application'],
+    keyName: 'includeApps',
+    type: 'string[]',
+    group: 'Build',
+    description: 'Will include the applications and all their dependency units to the build process',
+    process: (value) => {
+        if (!value)
+            return [];
+        return value.split(',').map(str => str.trim());
+    },
+    isArray: true,
+    dependencies: [
+        { param: BaiParam_UsePackage, value: (currentValue) => currentValue },
+        { param: BaiParam_BuildTree, value: true }
+    ]
+};
+export const BaiParam_ToESM = {
+    keys: ['-tesm', '--to-esm'],
+    keyName: 'toESM',
+    type: 'boolean',
+    group: 'Other',
+    description: 'Will migrate existing CJS code to ESM',
+    dependencies: [{ param: BaiParam_AllUnits, value: true }]
+};
+export const BaiParam_Simulate = {
+    keys: ['--simulate', '-sim', '--simulation'],
+    keyName: 'simulation',
+    type: 'boolean',
+    group: 'Other',
+    description: 'In combination with other params, will not perform the outbound operation, but instead simulate it',
+    dependencies: [{ param: BaiParam_AllUnits, value: true }]
+};
+export const BaiParam_CheckCyclicImports = {
+    keys: ['--check-cyclic-imports', '-cci'],
+    keyName: 'checkCyclicImports',
+    type: 'boolean',
+    group: 'General',
+    description: 'will check for cyclic imports and render an svg with the import graph',
+    dependencies: [
+        { param: BaiParam_NoBuild, value: true },
+        { param: BaiParam_Launch, value: false },
+        { param: BaiParam_Install, value: false },
+        { param: BaiParam_Deploy, value: false },
+        { param: BaiParam_Publish, value: false },
+        { param: BaiParam_Purge, value: false },
+        { param: BaiParam_Clean, value: false },
+    ]
+};
+export const BaiParam_ExtractDynamicDeps = {
+    keys: ['--extract-dynamic-deps', '-edd'],
+    keyName: 'extractDynamicDeps',
+    type: 'boolean',
+    group: 'Build',
+    description: 'Extract dynamic dependencies from TypeScript files and write to _dynamic-deps.json',
+    dependencies: [{ param: BaiParam_AllUnits, value: true }]
+};
+export const BaiParam_MapExports = {
+    keys: ['--map-exports', '-me'],
+    keyName: 'mapExports',
+    type: 'boolean',
+    group: 'Build',
+    description: 'Map all exported symbols from TypeScript files and write to _export-for-import.json',
+    dependencies: [{ param: BaiParam_AllUnits, value: true }]
+};
+export const BaiParam_IndicesMcpServer = {
+    keys: ['--indices-mcp-server', '-imcp'],
+    keyName: 'indicesMcpServer',
+    type: 'boolean',
+    group: 'Launch',
+    description: 'Start Export Indices MCP server for export index queries'
+};
+export const BaiParam_IndicesMcpPort = {
+    keys: ['--indices-mcp-port'],
+    keyName: 'indicesMcpPort',
+    type: 'number',
+    group: 'Launch',
+    description: 'Port for Export Indices MCP server (default: 3001)',
+    dependencies: [{ param: BaiParam_IndicesMcpServer, value: true }]
+};
+export const AllBaiParams = [
+    BaiParam_AllUnits,
+    BaiParam_DependencyTree,
+    BaiParam_CheckCyclicImports,
+    BaiParam_Purge,
+    BaiParam_Clean,
+    BaiParam_continue,
+    BaiParam_Prepare,
+    BaiParam_SetEnv,
+    BaiParam_Install,
+    BaiParam_Generate, // TODO: to implement
+    BaiParam_GenerateDocs, // TODO: to implement
+    BaiParam_NoBuild,
+    BaiParam_Apps,
+    BaiParam_DryRun,
+    BaiParam_Lint,
+    BaiParam_Watch,
+    BaiParam_WatchBuildTree,
+    BaiParam_Test,
+    BaiParam_TestType,
+    BaiParam_TestFile,
+    BaiParam_TestCase,
+    BaiParam_TestDebugPort,
+    BaiParam_Launch,
+    BaiParam_Deploy,
+    BaiParam_BuildPushImage,
+    BaiParam_DeployImage,
+    BaiParam_DeployFunction,
+    BaiParam_DeleteFunctions,
+    BaiParam_DeleteFunction,
+    BaiParam_DebugBackend,
+    BaiParam_Debug,
+    BaiParam_Verbose,
+    BaiParam_Publish,
+    BaiParam_UsePackage,
+    BaiParam_ToESM,
+    BaiParam_Simulate,
+    BaiParam_BuildTree,
+    BaiParam_ExtractDynamicDeps,
+    BaiParam_MapExports,
+    BaiParam_IndicesMcpServer,
+    BaiParam_IndicesMcpPort,
+    BaiParam_DebugLifecycle
+];

package/{v3/core → core}/types.d.ts

@@ -1,6 +1,6 @@
 import { AsyncVoidFunction } from '@nu-art/ts-common';
 import { BaseUnit } from '../units/index.js';
-import { Phase } from '../phase/index.js';
+import { Phase } from '../phases/definitions/index.js';
 export type Unit<P extends Phase<string>[]> = BaseUnit & UnitPhaseImplementor<P>;
 export type UnitPhaseImplementor<P extends Phase<string>[]> = {
     [K in P[number]['method']]: AsyncVoidFunction;

package/{v3/UnitsDependencyMapper → dependencies}/UnitsDependencyMapper.d.ts

@@ -4,7 +4,27 @@ export type UnitDependentNode = {
     dependsOn: string[];
 };
 /**
- * Maps unit dependencies and provides tools to analyze and operate on the dependency graph.
+ * Manages unit dependency graph and provides dependency analysis operations.
+ *
+ * **Key Operations**:
+ * - **buildDependencyTree()**: Builds layers of units ordered by dependencies (dependencies first)
+ * - **getTransitiveDependencies()**: Gets all transitive dependencies for given units
+ * - **getReverseDependencies()**: Gets all units that depend on given units
+ * - **filterDependencies()**: Filters dependency graph to only include specified units
+ *
+ * **Dependency Graph**:
+ * - Units are nodes, dependencies are edges
+ * - Validates all dependencies exist (throws if unknown dependency)
+ * - Supports pruning (removing non-participating units from graph)
+ *
+ * **Tree Building Algorithm**:
+ * 1. Builds reverse dependency map (who depends on whom)
+ * 2. Finds leaf nodes (no dependents)
+ * 3. Removes leaves and adds to current layer
+ * 4. Repeats until all nodes processed
+ * 5. Returns layers from bottom (dependencies) to top (dependents)
+ *
+ * **Usage**: Used by Workspace to determine execution order and resolve transitive dependencies.
  */
 export declare class UnitsDependencyMapper extends Logger {
     private readonly map;

package/{v3/UnitsDependencyMapper → dependencies}/UnitsDependencyMapper.js

@@ -2,7 +2,27 @@ import { __stringify, _keys, _values, BadImplementationException, DateTimeFormat
 import { FileSystemUtils } from '@nu-art/ts-common/utils/FileSystemUtils';
 import { resolve } from 'path';
 /**
- * Maps unit dependencies and provides tools to analyze and operate on the dependency graph.
+ * Manages unit dependency graph and provides dependency analysis operations.
+ *
+ * **Key Operations**:
+ * - **buildDependencyTree()**: Builds layers of units ordered by dependencies (dependencies first)
+ * - **getTransitiveDependencies()**: Gets all transitive dependencies for given units
+ * - **getReverseDependencies()**: Gets all units that depend on given units
+ * - **filterDependencies()**: Filters dependency graph to only include specified units
+ *
+ * **Dependency Graph**:
+ * - Units are nodes, dependencies are edges
+ * - Validates all dependencies exist (throws if unknown dependency)
+ * - Supports pruning (removing non-participating units from graph)
+ *
+ * **Tree Building Algorithm**:
+ * 1. Builds reverse dependency map (who depends on whom)
+ * 2. Finds leaf nodes (no dependents)
+ * 3. Removes leaves and adds to current layer
+ * 4. Repeats until all nodes processed
+ * 5. Returns layers from bottom (dependencies) to top (dependents)
+ *
+ * **Usage**: Used by Workspace to determine execution order and resolve transitive dependencies.
  */
 export class UnitsDependencyMapper extends Logger {
     map = {};
@@ -68,17 +88,20 @@ export class UnitsDependencyMapper extends Logger {
             layers.push(sortArray(bottomLayer));
         while (resolved.size < participatingKeys.length - topLayer.length) {
             const nextLayer = [];
+            let lastNode;
             for (const key of _keys(map)) {
                 const node = map[key];
                 if (resolved.has(key) || topLayer.includes(key))
                     continue;
-                if (node.dependsOn.every(dep => resolved.has(dep)))
+                if (node.dependsOn.every(dep => resolved.has(dep))) {
+                    lastNode = node;
                     nextLayer.push(key);
+                }
             }
             if (nextLayer.length === 0) {
                 this.logWarning(participatingKeys);
                 this.logWarning(map);
-                this.logWarning(layers);
+                this.logWarning(`Cyclic or disconnected dependency detected: ${lastNode?.key ?? '??'} and [${nextLayer.join(', ')}]`);
                 throw new Error('Cyclic or disconnected dependency detected');
             }
             nextLayer.sort();

package/dependencies/types.d.ts

@@ -0,0 +1 @@
+export * from './UnitsDependencyMapper.js';

package/dependencies/types.js

@@ -0,0 +1 @@
+export * from './UnitsDependencyMapper.js';

package/exceptions/PhaseAggregatedException.d.ts

@@ -0,0 +1,34 @@
+import { CustomException, Logger } from '@nu-art/ts-common';
+import { ScheduledStep } from '../phases/PhaseManager.js';
+import { UnitPhaseException } from './UnitPhaseException.js';
+/**
+ * Exception thrown when one or more phases fail during execution.
+ *
+ * **Aggregation**: Contains all `UnitPhaseException` errors from a failed step.
+ *
+ * **Error Formatting**: The `print()` method provides detailed error output:
+ * - For `CommandoException`: Shows message, cause, stdout, and stderr
+ * - For other errors: Shows error object
+ *
+ * **Usage**: Thrown by `PhaseManager.execute()` when any phase fails.
+ */
+export declare class PhaseAggregatedException extends CustomException {
+    errors: UnitPhaseException[];
+    /**
+     * Creates a new PhaseAggregatedException.
+     *
+     * @param errors - Array of unit/phase errors that occurred
+     * @param step - The step that failed
+     */
+    constructor(errors: UnitPhaseException[], step: ScheduledStep);
+    /**
+     * Prints detailed error information to logger.
+     *
+     * **Formatting**:
+     * - CommandoException: Shows message, cause, stdout, stderr
+     * - Other errors: Shows error object
+     *
+     * @param logger - Logger to print errors to
+     */
+    print(logger: Logger): void;
+}

package/{core/exceptions → exceptions}/PhaseAggregatedException.js

@@ -1,12 +1,38 @@
 import { CustomException, isErrorOfType } from '@nu-art/ts-common';
 import { CommandoException } from '@nu-art/commando/shell/core/CliError';
+/**
+ * Exception thrown when one or more phases fail during execution.
+ *
+ * **Aggregation**: Contains all `UnitPhaseException` errors from a failed step.
+ *
+ * **Error Formatting**: The `print()` method provides detailed error output:
+ * - For `CommandoException`: Shows message, cause, stdout, and stderr
+ * - For other errors: Shows error object
+ *
+ * **Usage**: Thrown by `PhaseManager.execute()` when any phase fails.
+ */
 export class PhaseAggregatedException extends CustomException {
     errors;
+    /**
+     * Creates a new PhaseAggregatedException.
+     *
+     * @param errors - Array of unit/phase errors that occurred
+     * @param step - The step that failed
+     */
     constructor(errors, step) {
         super(PhaseAggregatedException, `One or more errors occurred in step execution: ${JSON.stringify(step)}`);
         // @ts-ignore
         this.errors = errors;
     }
+    /**
+     * Prints detailed error information to logger.
+     *
+     * **Formatting**:
+     * - CommandoException: Shows message, cause, stdout, stderr
+     * - Other errors: Shows error object
+     *
+     * @param logger - Logger to print errors to
+     */
     print(logger) {
         logger.logError(this.message);
         this.errors.forEach(error => {

package/exceptions/UnitPhaseException.d.ts

@@ -0,0 +1,20 @@
+import { CustomException } from '@nu-art/ts-common';
+import { BaseUnit } from '../units/index.js';
+/**
+ * Exception thrown when a specific phase fails on a specific unit.
+ *
+ * **Context**: Contains the unit and phase that failed, along with the underlying error.
+ *
+ * **Usage**: Created by `PhaseManager.execute()` when a phase method throws an error.
+ * Multiple `UnitPhaseException`s are aggregated into `PhaseAggregatedException`.
+ */
+export declare class UnitPhaseException extends CustomException {
+    /**
+     * Creates a new UnitPhaseException.
+     *
+     * @param cause - The underlying error that occurred
+     * @param unit - The unit that failed
+     * @param phase - The phase key that failed
+     */
+    constructor(cause: Error, unit: BaseUnit, phase: string);
+}

package/exceptions/UnitPhaseException.js

@@ -0,0 +1,21 @@
+import { CustomException } from '@nu-art/ts-common';
+/**
+ * Exception thrown when a specific phase fails on a specific unit.
+ *
+ * **Context**: Contains the unit and phase that failed, along with the underlying error.
+ *
+ * **Usage**: Created by `PhaseManager.execute()` when a phase method throws an error.
+ * Multiple `UnitPhaseException`s are aggregated into `PhaseAggregatedException`.
+ */
+export class UnitPhaseException extends CustomException {
+    /**
+     * Creates a new UnitPhaseException.
+     *
+     * @param cause - The underlying error that occurred
+     * @param unit - The unit that failed
+     * @param phase - The phase key that failed
+     */
+    constructor(cause, unit, phase) {
+        super(UnitPhaseException, `Error in ${unit.config.key} (${phase})`, cause);
+    }
+}

package/exports/ExportIndexCache.d.ts

@@ -0,0 +1,25 @@
+import { ExportSymbol } from './ExportMapper.js';
+type CachedExportIndex = {
+    exports: ExportSymbol[];
+    byName: Map<string, ExportSymbol>;
+    byFile: Map<string, ExportSymbol[]>;
+    byType: Map<string, ExportSymbol[]>;
+    indexMtime: number;
+    sourceMtime: number;
+    packageRoot: string;
+    packageName: string;
+    projectRoot: string;
+};
+export declare const ExportIndexCache: {
+    getIndexPath(projectRoot: string, packageName: string): string;
+    load(projectRoot: string, packageRoot: string, packageName: string): Promise<CachedExportIndex>;
+    calculateSourceMtime(packageRoot: string): Promise<number>;
+    isStale(projectRoot: string, packageRoot: string, packageName: string): Promise<boolean>;
+    getByName(projectRoot: string, packageRoot: string, packageName: string, symbolName: string): Promise<ExportSymbol | null>;
+    getByFile(projectRoot: string, packageRoot: string, packageName: string, filePath: string): Promise<ExportSymbol[]>;
+    getByType(projectRoot: string, packageRoot: string, packageName: string, symbolType: string): Promise<ExportSymbol[]>;
+    getAll(projectRoot: string, packageRoot: string, packageName: string): Promise<ExportSymbol[]>;
+    invalidate(projectRoot: string, packageRoot: string, packageName: string): void;
+    clear(): void;
+};
+export {};