@eldrforge/kodrdriv 1.2.4 → 1.2.6

package/dist/commands/tree.js

@@ -114,6 +114,11 @@ const updateInterProjectDependencies = async (packageDir, publishedVersions, all
         ];
         for (const publishedVersion of publishedVersions){
             const { packageName, version } = publishedVersion;
+            // Do not propagate prerelease versions to consumers (often not available on registry)
+            if (typeof version === 'string' && version.includes('-')) {
+                packageLogger.verbose(`Skipping prerelease version for ${packageName}: ${version}`);
+                continue;
+            }
             // Only update if this is an inter-project dependency (exists in our build tree)
             if (!allPackageNames.has(packageName)) {
                 continue;
@@ -222,6 +227,84 @@ const cleanupContext = async (outputDirectory)=>{
         logger.warn(`Warning: Failed to cleanup execution context: ${error.message}`);
     }
 };
+// Helper function to promote a package to completed status in the context
+const promotePackageToCompleted = async (packageName, outputDirectory)=>{
+    const storage = create({
+        log: ()=>{}
+    });
+    const contextFilePath = getContextFilePath(outputDirectory);
+    try {
+        if (!await storage.exists(contextFilePath)) {
+            return;
+        }
+        const contextContent = await storage.readFile(contextFilePath, 'utf-8');
+        const contextData = safeJsonParse(contextContent, contextFilePath);
+        // Restore dates from ISO strings
+        const context = {
+            ...contextData,
+            startTime: new Date(contextData.startTime),
+            lastUpdateTime: new Date(contextData.lastUpdateTime),
+            publishedVersions: contextData.publishedVersions.map((v)=>({
+                    ...v,
+                    publishTime: new Date(v.publishTime)
+                }))
+        };
+        // Add package to completed list if not already there
+        if (!context.completedPackages.includes(packageName)) {
+            context.completedPackages.push(packageName);
+            context.lastUpdateTime = new Date();
+            await saveExecutionContext(context, outputDirectory);
+        }
+    } catch (error) {
+        const logger = getLogger();
+        logger.warn(`Warning: Failed to promote package to completed: ${error.message}`);
+    }
+};
+// Helper function to validate that all packages have the required scripts
+const validateScripts = async (packages, scripts)=>{
+    const logger = getLogger();
+    const missingScripts = new Map();
+    const storage = create({
+        log: ()=>{}
+    });
+    logger.debug(`Validating scripts: ${scripts.join(', ')}`);
+    for (const [packageName, packageInfo] of packages){
+        const packageJsonPath = path__default.join(packageInfo.path, 'package.json');
+        const missingForPackage = [];
+        try {
+            const packageJsonContent = await storage.readFile(packageJsonPath, 'utf-8');
+            const packageJson = safeJsonParse(packageJsonContent, packageJsonPath);
+            const validated = validatePackageJson(packageJson, packageJsonPath);
+            // Check if each required script exists
+            for (const script of scripts){
+                if (!validated.scripts || !validated.scripts[script]) {
+                    missingForPackage.push(script);
+                }
+            }
+            if (missingForPackage.length > 0) {
+                missingScripts.set(packageName, missingForPackage);
+                logger.debug(`Package ${packageName} missing scripts: ${missingForPackage.join(', ')}`);
+            }
+        } catch (error) {
+            logger.debug(`Error reading package.json for ${packageName}: ${error.message}`);
+            // If we can't read the package.json, assume all scripts are missing
+            missingScripts.set(packageName, scripts);
+        }
+    }
+    const valid = missingScripts.size === 0;
+    if (valid) {
+        logger.info(`✅ All packages have the required scripts: ${scripts.join(', ')}`);
+    } else {
+        logger.error(`❌ Script validation failed. Missing scripts:`);
+        for (const [packageName, missing] of missingScripts){
+            logger.error(`  ${packageName}: ${missing.join(', ')}`);
+        }
+    }
+    return {
+        valid,
+        missingScripts
+    };
+};
 // Extract published version from package.json after successful publish
 const extractPublishedVersion = async (packageDir, packageLogger)=>{
     const storage = create({
@@ -313,7 +396,7 @@ const createPackageLogger = (packageName, sequenceNumber, totalCount, isDryRun =
     };
 };
 // Helper function to format subproject error output
-const formatSubprojectError = (packageName, error)=>{
+const formatSubprojectError = (packageName, error, _packageInfo, _position, _total)=>{
     const lines = [];
     lines.push(`❌ Command failed in package ${packageName}:`);
     // Format the main error message with indentation
@@ -592,6 +675,7 @@ const executePackage = async (packageName, packageInfo, commandToRun, runConfig,
                 }
                 // For built-in commands, shell out to a separate kodrdriv process
                 // This preserves individual project configurations
+                let publishWasSkipped;
                 if (isBuiltInCommand) {
                     // Extract the command name from "kodrdriv <command>"
                     const builtInCommandName = commandToRun.replace('kodrdriv ', '');
@@ -601,28 +685,39 @@ const executePackage = async (packageName, packageInfo, commandToRun, runConfig,
                     // Ensure dry-run propagates to subprocess even during overall dry-run mode
                     const effectiveCommand = runConfig.dryRun && !commandToRun.includes('--dry-run') ? `${commandToRun} --dry-run` : commandToRun;
                     // Use runWithLogging for built-in commands to capture all output
-                    await runWithLogging(effectiveCommand, packageLogger, {}, showOutput);
+                    const { stdout } = await runWithLogging(effectiveCommand, packageLogger, {}, showOutput);
+                    // Detect explicit skip marker from publish to avoid propagating versions
+                    if (builtInCommandName === 'publish' && stdout && stdout.includes('KODRDRIV_PUBLISH_SKIPPED')) {
+                        packageLogger.info('Publish skipped for this package; will not record or propagate a version.');
+                        publishWasSkipped = true;
+                    }
                 } else {
                     // For custom commands, use the existing logic
                     await runWithLogging(commandToRun, packageLogger, {}, showOutput);
                 }
                 // Track published version after successful publish (skip during dry run)
                 if (!isDryRun && isBuiltInCommand && commandToRun.includes('publish')) {
-                    const publishedVersion = await extractPublishedVersion(packageDir, packageLogger);
-                    if (publishedVersion) {
-                        let mutexLocked = false;
-                        try {
-                            await globalStateMutex.lock();
-                            mutexLocked = true;
-                            publishedVersions.push(publishedVersion);
-                            packageLogger.info(`Tracked published version: ${publishedVersion.packageName}@${publishedVersion.version}`);
-                            globalStateMutex.unlock();
-                            mutexLocked = false;
-                        } catch (error) {
-                            if (mutexLocked) {
+                    // If publish was skipped, do not record a version
+                    if (publishWasSkipped) {
+                        packageLogger.verbose('Skipping version tracking due to earlier skip.');
+                    } else {
+                        // Only record a published version if a new tag exists (avoid recording for skipped publishes)
+                        const publishedVersion = await extractPublishedVersion(packageDir, packageLogger);
+                        if (publishedVersion) {
+                            let mutexLocked = false;
+                            try {
+                                await globalStateMutex.lock();
+                                mutexLocked = true;
+                                publishedVersions.push(publishedVersion);
+                                packageLogger.info(`Tracked published version: ${publishedVersion.packageName}@${publishedVersion.version}`);
                                 globalStateMutex.unlock();
+                                mutexLocked = false;
+                            } catch (error) {
+                                if (mutexLocked) {
+                                    globalStateMutex.unlock();
+                                }
+                                throw error;
                             }
-                            throw error;
                         }
                     }
                 }
@@ -654,22 +749,36 @@ const executePackage = async (packageName, packageInfo, commandToRun, runConfig,
             success: true
         };
     } catch (error) {
+        var _error_message;
         if (runConfig.debug || runConfig.verbose) {
             packageLogger.error(`❌ Execution failed: ${error.message}`);
         } else {
             logger.error(`[${index + 1}/${total}] ${packageName}: ❌ Failed - ${error.message}`);
         }
+        // Check if this is a timeout error
+        const errorMessage = ((_error_message = error.message) === null || _error_message === void 0 ? void 0 : _error_message.toLowerCase()) || '';
+        const isTimeoutError = errorMessage && (errorMessage.includes('timeout waiting for pr') || errorMessage.includes('timeout waiting for release workflows') || errorMessage.includes('timeout reached') || errorMessage.includes('timeout') || errorMessage.includes('timed out') || errorMessage.includes('timed_out'));
         return {
             success: false,
-            error
+            error,
+            isTimeoutError
         };
     }
 };
 const execute = async (runConfig)=>{
-    var _runConfig_tree, _runConfig_tree1, _runConfig_tree2, _runConfig_tree3, _runConfig_tree4;
+    var _runConfig_tree, _runConfig_tree1, _runConfig_tree2, _runConfig_tree3, _runConfig_tree4, _runConfig_tree5;
     const logger = getLogger();
     const isDryRun = runConfig.dryRun || false;
     const isContinue = ((_runConfig_tree = runConfig.tree) === null || _runConfig_tree === void 0 ? void 0 : _runConfig_tree.continue) || false;
+    const promotePackage = (_runConfig_tree1 = runConfig.tree) === null || _runConfig_tree1 === void 0 ? void 0 : _runConfig_tree1.promote;
+    // Handle promote mode
+    if (promotePackage) {
+        logger.info(`Promoting package '${promotePackage}' to completed status...`);
+        await promotePackageToCompleted(promotePackage, runConfig.outputDirectory);
+        logger.info(`✅ Package '${promotePackage}' has been marked as completed.`);
+        logger.info('You can now run the tree command with --continue to resume from the next package.');
+        return `Package '${promotePackage}' promoted to completed status.`;
+    }
     // Handle continue mode
     if (isContinue) {
         const savedContext = await loadExecutionContext(runConfig.outputDirectory);
@@ -708,24 +817,50 @@ const execute = async (runConfig)=>{
         executionContext = null;
     }
     // Check if we're in built-in command mode (tree command with second argument)
-    const builtInCommand = (_runConfig_tree1 = runConfig.tree) === null || _runConfig_tree1 === void 0 ? void 0 : _runConfig_tree1.builtInCommand;
+    const builtInCommand = (_runConfig_tree2 = runConfig.tree) === null || _runConfig_tree2 === void 0 ? void 0 : _runConfig_tree2.builtInCommand;
     const supportedBuiltInCommands = [
         'commit',
         'publish',
         'link',
         'unlink',
         'development',
-        'branches'
+        'branches',
+        'run'
     ];
     if (builtInCommand && !supportedBuiltInCommands.includes(builtInCommand)) {
         throw new Error(`Unsupported built-in command: ${builtInCommand}. Supported commands: ${supportedBuiltInCommands.join(', ')}`);
     }
+    // Handle run subcommand - convert space-separated scripts to npm run commands
+    if (builtInCommand === 'run') {
+        var _runConfig_tree6;
+        const packageArgument = (_runConfig_tree6 = runConfig.tree) === null || _runConfig_tree6 === void 0 ? void 0 : _runConfig_tree6.packageArgument;
+        if (!packageArgument) {
+            throw new Error('run subcommand requires script names. Usage: kodrdriv tree run "clean build test"');
+        }
+        // Split the package argument by spaces to get individual script names
+        const scripts = packageArgument.trim().split(/\s+/).filter((script)=>script.length > 0);
+        if (scripts.length === 0) {
+            throw new Error('run subcommand requires at least one script name. Usage: kodrdriv tree run "clean build test"');
+        }
+        // Convert to npm run commands joined with &&
+        const npmCommands = scripts.map((script)=>`npm run ${script}`).join(' && ');
+        // Set this as the custom command to run
+        runConfig.tree = {
+            ...runConfig.tree,
+            cmd: npmCommands
+        };
+        // Clear the built-in command since we're now using custom command mode
+        runConfig.tree.builtInCommand = undefined;
+        logger.info(`Converting run subcommand to: ${npmCommands}`);
+        // Store scripts for later validation
+        runConfig.__scriptsToValidate = scripts;
+    }
     // Determine the target directories - either specified or current working directory
-    const directories = ((_runConfig_tree2 = runConfig.tree) === null || _runConfig_tree2 === void 0 ? void 0 : _runConfig_tree2.directories) || [
+    const directories = ((_runConfig_tree3 = runConfig.tree) === null || _runConfig_tree3 === void 0 ? void 0 : _runConfig_tree3.directories) || [
         process.cwd()
     ];
     // Handle link status subcommand
-    if (builtInCommand === 'link' && ((_runConfig_tree3 = runConfig.tree) === null || _runConfig_tree3 === void 0 ? void 0 : _runConfig_tree3.packageArgument) === 'status') {
+    if (builtInCommand === 'link' && ((_runConfig_tree4 = runConfig.tree) === null || _runConfig_tree4 === void 0 ? void 0 : _runConfig_tree4.packageArgument) === 'status') {
         // For tree link status, we want to show status across all packages
         logger.info(`${isDryRun ? 'DRY RUN: ' : ''}Running link status across workspace...`);
         // Create a config that will be passed to the link command
@@ -745,7 +880,7 @@ const execute = async (runConfig)=>{
         }
     }
     // Handle unlink status subcommand
-    if (builtInCommand === 'unlink' && ((_runConfig_tree4 = runConfig.tree) === null || _runConfig_tree4 === void 0 ? void 0 : _runConfig_tree4.packageArgument) === 'status') {
+    if (builtInCommand === 'unlink' && ((_runConfig_tree5 = runConfig.tree) === null || _runConfig_tree5 === void 0 ? void 0 : _runConfig_tree5.packageArgument) === 'status') {
         // For tree unlink status, we want to show status across all packages
         logger.info(`${isDryRun ? 'DRY RUN: ' : ''}Running unlink status across workspace...`);
         // Create a config that will be passed to the unlink command
@@ -770,9 +905,9 @@ const execute = async (runConfig)=>{
         logger.info(`${isDryRun ? 'DRY RUN: ' : ''}Analyzing workspaces at: ${directories.join(', ')}`);
     }
     try {
-        var _runConfig_tree5, _runConfig_tree6, _runConfig_tree7, _runConfig_tree8;
+        var _runConfig_tree7, _runConfig_tree8, _runConfig_tree9, _runConfig_tree10;
         // Get exclusion patterns from config, fallback to empty array
-        const excludedPatterns = ((_runConfig_tree5 = runConfig.tree) === null || _runConfig_tree5 === void 0 ? void 0 : _runConfig_tree5.exclude) || [];
+        const excludedPatterns = ((_runConfig_tree7 = runConfig.tree) === null || _runConfig_tree7 === void 0 ? void 0 : _runConfig_tree7.exclude) || [];
         if (excludedPatterns.length > 0) {
             logger.verbose(`${isDryRun ? 'DRY RUN: ' : ''}Using exclusion patterns: ${excludedPatterns.join(', ')}`);
         }
@@ -799,16 +934,19 @@ const execute = async (runConfig)=>{
         logger.verbose(`${isDryRun ? 'DRY RUN: ' : ''}Determining build order...`);
         let buildOrder = topologicalSort(dependencyGraph);
         // Handle start-from functionality if specified
-        const startFrom = (_runConfig_tree6 = runConfig.tree) === null || _runConfig_tree6 === void 0 ? void 0 : _runConfig_tree6.startFrom;
+        const startFrom = (_runConfig_tree8 = runConfig.tree) === null || _runConfig_tree8 === void 0 ? void 0 : _runConfig_tree8.startFrom;
         if (startFrom) {
             logger.verbose(`${isDryRun ? 'DRY RUN: ' : ''}Looking for start package: ${startFrom}`);
-            // Find the package that matches the startFrom directory name
-            const startIndex = buildOrder.findIndex((packageName)=>{
-                const packageInfo = dependencyGraph.packages.get(packageName);
-                const dirName = path__default.basename(packageInfo.path);
-                return dirName === startFrom || packageName === startFrom;
-            });
-            if (startIndex === -1) {
+            // Resolve the actual package name (can be package name or directory name)
+            let startPackageName = null;
+            for (const [pkgName, pkgInfo] of dependencyGraph.packages){
+                const dirName = path__default.basename(pkgInfo.path);
+                if (dirName === startFrom || pkgName === startFrom) {
+                    startPackageName = pkgName;
+                    break;
+                }
+            }
+            if (!startPackageName) {
                 // Check if the package exists but was excluded across all directories
                 let allPackageJsonPathsForCheck = [];
                 for (const targetDirectory of directories){
@@ -842,14 +980,18 @@ const execute = async (runConfig)=>{
                     throw new Error(`Package directory '${startFrom}' not found. Available packages: ${availablePackages}`);
                 }
             }
-            const skippedCount = startIndex;
-            buildOrder = buildOrder.slice(startIndex);
-            if (skippedCount > 0) {
-                logger.info(`${isDryRun ? 'DRY RUN: ' : ''}Resuming from '${startFrom}' - skipping ${skippedCount} package${skippedCount === 1 ? '' : 's'}`);
+            // Find the start package in the build order and start execution from there
+            const startIndex = buildOrder.findIndex((pkgName)=>pkgName === startPackageName);
+            if (startIndex === -1) {
+                throw new Error(`Package '${startFrom}' not found in build order. This should not happen.`);
             }
+            // Filter build order to start from the specified package
+            const originalLength = buildOrder.length;
+            buildOrder = buildOrder.slice(startIndex);
+            logger.info(`${isDryRun ? 'DRY RUN: ' : ''}Starting execution from package '${startFrom}' (${buildOrder.length} of ${originalLength} packages remaining).`);
         }
         // Handle stop-at functionality if specified
-        const stopAt = (_runConfig_tree7 = runConfig.tree) === null || _runConfig_tree7 === void 0 ? void 0 : _runConfig_tree7.stopAt;
+        const stopAt = (_runConfig_tree9 = runConfig.tree) === null || _runConfig_tree9 === void 0 ? void 0 : _runConfig_tree9.stopAt;
         if (stopAt) {
             logger.verbose(`${isDryRun ? 'DRY RUN: ' : ''}Looking for stop package: ${stopAt}`);
             // Find the package that matches the stopAt directory name
@@ -1208,12 +1350,12 @@ const execute = async (runConfig)=>{
             returnOutput = `\nBuild order: ${buildOrder.join(' → ')}\n`;
         }
         // Execute command if provided (custom command or built-in command)
-        const cmd = (_runConfig_tree8 = runConfig.tree) === null || _runConfig_tree8 === void 0 ? void 0 : _runConfig_tree8.cmd;
+        const cmd = (_runConfig_tree10 = runConfig.tree) === null || _runConfig_tree10 === void 0 ? void 0 : _runConfig_tree10.cmd;
         // Determine command to execute
         let commandToRun;
         let isBuiltInCommand = false;
         if (builtInCommand) {
-            var _runConfig_tree9, _runConfig_tree10, _runConfig_tree11;
+            var _runConfig_tree11, _runConfig_tree12, _runConfig_tree13;
             // Built-in command mode: shell out to kodrdriv subprocess
             // Build command with propagated global options
             const globalOptions = [];
@@ -1230,14 +1372,14 @@ const execute = async (runConfig)=>{
             // Build the command with global options
             const optionsString = globalOptions.length > 0 ? ` ${globalOptions.join(' ')}` : '';
             // Add package argument for link/unlink commands
-            const packageArg = (_runConfig_tree9 = runConfig.tree) === null || _runConfig_tree9 === void 0 ? void 0 : _runConfig_tree9.packageArgument;
+            const packageArg = (_runConfig_tree11 = runConfig.tree) === null || _runConfig_tree11 === void 0 ? void 0 : _runConfig_tree11.packageArgument;
             const packageArgString = packageArg && (builtInCommand === 'link' || builtInCommand === 'unlink') ? ` "${packageArg}"` : '';
             // Add command-specific options
             let commandSpecificOptions = '';
-            if (builtInCommand === 'unlink' && ((_runConfig_tree10 = runConfig.tree) === null || _runConfig_tree10 === void 0 ? void 0 : _runConfig_tree10.cleanNodeModules)) {
+            if (builtInCommand === 'unlink' && ((_runConfig_tree12 = runConfig.tree) === null || _runConfig_tree12 === void 0 ? void 0 : _runConfig_tree12.cleanNodeModules)) {
                 commandSpecificOptions += ' --clean-node-modules';
             }
-            if ((builtInCommand === 'link' || builtInCommand === 'unlink') && ((_runConfig_tree11 = runConfig.tree) === null || _runConfig_tree11 === void 0 ? void 0 : _runConfig_tree11.externals) && runConfig.tree.externals.length > 0) {
+            if ((builtInCommand === 'link' || builtInCommand === 'unlink') && ((_runConfig_tree13 = runConfig.tree) === null || _runConfig_tree13 === void 0 ? void 0 : _runConfig_tree13.externals) && runConfig.tree.externals.length > 0) {
                 commandSpecificOptions += ` --externals ${runConfig.tree.externals.join(' ')}`;
             }
             commandToRun = `kodrdriv ${builtInCommand}${optionsString}${packageArgString}${commandSpecificOptions}`;
@@ -1247,6 +1389,23 @@ const execute = async (runConfig)=>{
             commandToRun = cmd;
         }
         if (commandToRun) {
+            // Validate scripts for run command before execution
+            const scriptsToValidate = runConfig.__scriptsToValidate;
+            if (scriptsToValidate && scriptsToValidate.length > 0) {
+                logger.info(`🔍 Validating scripts before execution: ${scriptsToValidate.join(', ')}`);
+                const validation = await validateScripts(dependencyGraph.packages, scriptsToValidate);
+                if (!validation.valid) {
+                    logger.error('');
+                    logger.error('❌ Script validation failed. Cannot proceed with execution.');
+                    logger.error('');
+                    logger.error('💡 To fix this:');
+                    logger.error('   1. Add the missing scripts to the package.json files');
+                    logger.error('   2. Or exclude packages that don\'t need these scripts using --exclude');
+                    logger.error('   3. Or run individual packages that have the required scripts');
+                    logger.error('');
+                    throw new Error('Script validation failed. See details above.');
+                }
+            }
             // Create set of all package names for inter-project dependency detection
             const allPackageNames = new Set(Array.from(dependencyGraph.packages.keys()));
             // Initialize execution context if not continuing
@@ -1260,8 +1419,8 @@ const execute = async (runConfig)=>{
                     startTime: new Date(),
                     lastUpdateTime: new Date()
                 };
-                // Save initial context
-                if (isBuiltInCommand && builtInCommand === 'publish' && !isDryRun) {
+                // Save initial context for commands that support continuation
+                if (isBuiltInCommand && (builtInCommand === 'publish' || builtInCommand === 'run') && !isDryRun) {
                     await saveExecutionContext(executionContext, runConfig.outputDirectory);
                 }
             }
@@ -1291,7 +1450,7 @@ const execute = async (runConfig)=>{
                 if (result.success) {
                     successCount++;
                     // Update context
-                    if (executionContext && isBuiltInCommand && builtInCommand === 'publish' && !isDryRun) {
+                    if (executionContext && isBuiltInCommand && (builtInCommand === 'publish' || builtInCommand === 'run') && !isDryRun) {
                         executionContext.completedPackages.push(packageName);
                         executionContext.publishedVersions = publishedVersions;
                         executionContext.lastUpdateTime = new Date();
@@ -1304,17 +1463,76 @@ const execute = async (runConfig)=>{
                     }
                 } else {
                     failedPackage = packageName;
-                    const formattedError = formatSubprojectError(packageName, result.error);
+                    const formattedError = formatSubprojectError(packageName, result.error, packageInfo, i + 1, buildOrder.length);
                     if (!isDryRun) {
+                        var _result_error;
                         packageLogger.error(`Execution failed`);
                         logger.error(formattedError);
                         logger.error(`Failed after ${successCount} successful packages.`);
+                        // Special handling for timeout errors
+                        if (result.isTimeoutError) {
+                            logger.error('');
+                            logger.error('⏰ TIMEOUT DETECTED: This appears to be a timeout error.');
+                            logger.error('   This commonly happens when PR checks take longer than expected.');
+                            logger.error('   The execution context has been saved for recovery.');
+                            logger.error('');
+                            // Save context even on timeout for recovery
+                            if (executionContext && isBuiltInCommand && (builtInCommand === 'publish' || builtInCommand === 'run')) {
+                                executionContext.completedPackages.push(packageName);
+                                executionContext.publishedVersions = publishedVersions;
+                                executionContext.lastUpdateTime = new Date();
+                                await saveExecutionContext(executionContext, runConfig.outputDirectory);
+                                logger.info('💾 Execution context saved for recovery.');
+                            }
+                            // For publish commands, provide specific guidance about CI/CD setup
+                            if (builtInCommand === 'publish') {
+                                logger.error('');
+                                logger.error('💡 PUBLISH TIMEOUT TROUBLESHOOTING:');
+                                logger.error('   This project may not have CI/CD workflows configured.');
+                                logger.error('   Common solutions:');
+                                logger.error('   1. Set up GitHub Actions workflows for this repository');
+                                logger.error('   2. Use --sendit flag to skip user confirmation:');
+                                logger.error(`      kodrdriv tree publish --sendit`);
+                                logger.error('   3. Or manually promote this package:');
+                                logger.error(`      kodrdriv tree publish --promote ${packageName}`);
+                                logger.error('');
+                            }
+                        }
                         logger.error(`To resume from this point, run:`);
                         if (isBuiltInCommand) {
                             logger.error(`    kodrdriv tree ${builtInCommand} --continue`);
                         } else {
                             logger.error(`    kodrdriv tree --continue --cmd "${commandToRun}"`);
                         }
+                        // For timeout errors, provide additional recovery instructions
+                        if (result.isTimeoutError) {
+                            logger.error('');
+                            logger.error('🔧 RECOVERY OPTIONS:');
+                            if (builtInCommand === 'publish') {
+                                logger.error('   1. Wait for the PR checks to complete, then run:');
+                                logger.error(`      cd ${packageInfo.path}`);
+                                logger.error(`      kodrdriv publish`);
+                                logger.error('   2. After the individual publish completes, run:');
+                                logger.error(`      kodrdriv tree ${builtInCommand} --continue`);
+                            } else {
+                                logger.error('   1. Fix any issues in the package, then run:');
+                                logger.error(`      cd ${packageInfo.path}`);
+                                logger.error(`      ${commandToRun}`);
+                                logger.error('   2. After the command completes successfully, run:');
+                                logger.error(`      kodrdriv tree ${builtInCommand} --continue`);
+                            }
+                            logger.error('   3. Or promote this package to completed status:');
+                            logger.error(`      kodrdriv tree ${builtInCommand} --promote ${packageName}`);
+                            logger.error('   4. Or manually edit .kodrdriv-context to mark this package as completed');
+                        }
+                        // Add clear error summary at the very end
+                        logger.error('');
+                        logger.error('📋 ERROR SUMMARY:');
+                        logger.error(`   Project that failed: ${packageName}`);
+                        logger.error(`   Location: ${packageInfo.path}`);
+                        logger.error(`   Position in tree: ${i + 1} of ${buildOrder.length} packages`);
+                        logger.error(`   What failed: ${((_result_error = result.error) === null || _result_error === void 0 ? void 0 : _result_error.message) || 'Unknown error'}`);
+                        logger.error('');
                         throw new Error(`Command failed in package ${packageName}`);
                     }
                     break;
@@ -1324,7 +1542,7 @@ const execute = async (runConfig)=>{
                 const summary = `${isDryRun ? 'DRY RUN: ' : ''}All ${buildOrder.length} packages completed successfully! 🎉`;
                 logger.info(summary);
                 // Clean up context on successful completion
-                if (isBuiltInCommand && builtInCommand === 'publish' && !isDryRun) {
+                if (isBuiltInCommand && (builtInCommand === 'publish' || builtInCommand === 'run') && !isDryRun) {
                     await cleanupContext(runConfig.outputDirectory);
                 }
                 return returnOutput; // Don't duplicate the summary in return string