@lumenflow/cli 3.1.3 → 3.2.1

package/dist/release.js

@@ -4,15 +4,16 @@
 /**
  * Release Command
  *
- * Orchestrates npm release for all @lumenflow/* packages using micro-worktree isolation.
+ * Orchestrates npm release for all @lumenflow/* packages.
  *
  * Features:
  * - Validates semver version format
  * - Bumps all @lumenflow/* package versions atomically
- * - Uses micro-worktree isolation for version commit (no main branch pollution)
  * - Builds all packages via turbo
+ * - Validates packed artifacts against package contracts
  * - Publishes to npm with proper auth (requires NPM_TOKEN)
  * - Creates git tag vX.Y.Z
+ * - Cleanup-on-failure ensures main is never left dirty (WU-2062)
  *
  * Usage:
  *   pnpm release --release-version 1.3.0
@@ -25,21 +26,18 @@
  * WU-1074: Add release command for npm publishing
  */
 import { Command } from 'commander';
-import { existsSync, readFileSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, unlinkSync, } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
-import { execSync } from 'node:child_process';
+import { execFileSync, execSync } from 'node:child_process';
 import { getGitForCwd } from '@lumenflow/core/git-adapter';
 import { die } from '@lumenflow/core/error-handler';
-import { withMicroWorktree } from '@lumenflow/core/micro-worktree';
 import { ensureOnMain } from '@lumenflow/core/wu-helpers';
 import { REMOTES, FILE_SYSTEM, PKG_MANAGER } from '@lumenflow/core/wu-constants';
 import { runCLI } from './cli-entry-point.js';
 /** Log prefix for console output */
 const LOG_PREFIX = '[release]';
-/** Micro-worktree operation name */
-const OPERATION_NAME = 'release';
 /** Directory containing @lumenflow packages */
 const LUMENFLOW_PACKAGES_DIR = 'packages/@lumenflow';
 /** Path to the bare lumenflow wrapper package (WU-1691) */
@@ -65,6 +63,52 @@ const CHANGESET_DIR = '.changeset';
 const LUMENFLOW_FORCE_ENV = 'LUMENFLOW_FORCE';
 /** Environment variable to provide reason for force bypass */
 const LUMENFLOW_FORCE_REASON_ENV = 'LUMENFLOW_FORCE_REASON';
+/** Release phase label for pre-release clean-tree validation */
+const RELEASE_CLEAN_CHECK_PHASE_BEFORE_RELEASE = 'before release';
+/** Command shown when release fails due to dirty working tree */
+const GIT_STATUS_SHORT_COMMAND = 'git status --short';
+/** Guidance shown when generated artifacts dirty the repository */
+const CLEAN_TREE_RECOVERY_GUIDANCE = 'Commit, stash, or clean generated files before retrying release.';
+/** Package manifest filename */
+const PACKAGE_JSON_FILENAME = 'package.json';
+/** Source directory name used for build sanity checks */
+const SOURCE_DIR_NAME = 'src';
+/** Dist directory name used for release artifacts */
+const DIST_DIR_NAME = 'dist';
+/** Relative path prefix used in package manifests */
+const RELATIVE_PATH_PREFIX = './';
+/** Previous-pack sanity threshold (current must be >= 10% of previous) */
+const PREVIOUS_PACK_MIN_RATIO = 0.1;
+/** Path prefix emitted by some pack tools (for example package/dist/index.js) */
+const PACK_TOOL_PACKAGE_PREFIX = 'package/';
+/** Path prefixes used when normalizing manifest paths */
+const NODE_PROTOCOL_PREFIX = 'node:';
+const HTTP_PROTOCOL_PREFIX = 'http://';
+const HTTPS_PROTOCOL_PREFIX = 'https://';
+const PARENT_RELATIVE_PREFIX = '../';
+/** Path separator constants for normalization */
+const POSIX_PATH_SEPARATOR = '/';
+const WINDOWS_PATH_SEPARATOR = '\\';
+/** Labels for release logging phases */
+const PRE_FLIGHT_LABEL = 'preflight';
+const PACK_VALIDATE_LABEL = 'pack:validate';
+const PACK_BASELINE_LABEL = 'pack:baseline';
+/** Pack validation error messages */
+const PACK_EMPTY_OUTPUT_ERROR = 'pack command produced empty output';
+const PACK_INVALID_JSON_ERROR = 'pack command produced invalid JSON payload';
+const PACK_MISSING_FILES_ARRAY_ERROR = 'pack command JSON missing required files[]';
+const PACK_INVALID_FILES_ENTRY_ERROR = 'pack command JSON has invalid files[] entry';
+const PACK_ZERO_FILES_ERROR = 'pack dry-run returned zero files';
+const DIST_EMPTY_ERROR = 'dist directory has no files after build';
+const MISSING_CONTRACT_PREFIX = 'Missing packaged files declared by package.json contract: ';
+const RELEASE_VALIDATION_FAILURE_HEADER = 'Release artifact validation failed. Refusing to publish broken tarballs.';
+const RELEASE_VALIDATION_FAILURE_FOOTER = 'Fix the package exports/build outputs, then re-run release.';
+const DIST_BUILD_INCOMPLETE_PREFIX = 'dist has fewer files than src';
+const DIST_BUILD_INCOMPLETE_SUFFIX = 'build artifacts look incomplete';
+const PACK_COUNT_BELOW_BASELINE_PREFIX = 'packed file count';
+const PACK_COUNT_BELOW_BASELINE_MID = 'is below 10% of previous published version';
+const SKIP_BUILD_SYMLINK_ERROR_PREFIX = 'Refusing release with --skip-build:';
+const SKIP_BUILD_SYMLINK_ERROR_GUIDANCE = 'Run release without --skip-build so dist can be rebuilt as real files.';
 /**
  * Environment variable for WU tool identification (WU-1296)
  * Pre-push hook checks this to allow approved tool operations
@@ -101,6 +145,22 @@ export async function withReleaseEnv(fn) {
         }
     }
 }
+/**
+ * Assert the current git working tree is clean.
+ *
+ * @param git - Git adapter with cleanliness check
+ * @param phase - Human-readable release phase label
+ */
+export async function assertWorkingTreeClean(git, phase) {
+    const isClean = await git.isClean();
+    if (isClean) {
+        return;
+    }
+    die(`Working directory has uncommitted changes ${phase}.\n\n` +
+        `Run this command to inspect unexpected artifacts:\n` +
+        `  ${GIT_STATUS_SHORT_COMMAND}\n` +
+        `${CLEAN_TREE_RECOVERY_GUIDANCE}`);
+}
 /**
  * Validate that a string is a valid semver version
  *
@@ -128,7 +188,7 @@ export function findPackageJsonPaths(baseDir = process.cwd()) {
         const entries = readdirSync(packagesDir);
         for (const entry of entries) {
             const entryPath = join(packagesDir, entry);
-            const packageJsonPath = join(entryPath, 'package.json');
+            const packageJsonPath = join(entryPath, PACKAGE_JSON_FILENAME);
             if (statSync(entryPath).isDirectory() && existsSync(packageJsonPath)) {
                 // Read package.json to check if it's private
                 const content = JSON.parse(readFileSync(packageJsonPath, { encoding: FILE_SYSTEM.UTF8 }));
@@ -140,7 +200,7 @@ export function findPackageJsonPaths(baseDir = process.cwd()) {
         }
     }
     // WU-1691: Include the bare lumenflow wrapper package
-    const wrapperPackageJson = join(baseDir, LUMENFLOW_WRAPPER_PACKAGE, 'package.json');
+    const wrapperPackageJson = join(baseDir, LUMENFLOW_WRAPPER_PACKAGE, PACKAGE_JSON_FILENAME);
     if (existsSync(wrapperPackageJson)) {
         const content = JSON.parse(readFileSync(wrapperPackageJson, { encoding: FILE_SYSTEM.UTF8 }));
         if (!content.private) {
@@ -168,6 +228,227 @@ export async function updatePackageVersions(paths, version) {
         await writeFile(packagePath, updated, { encoding: FILE_SYSTEM.ENCODING });
     }
 }
+/**
+ * Convert manifest file paths (for example "./dist/index.js") into package-relative paths.
+ */
+function normalizeManifestPath(filePath) {
+    const trimmed = filePath.trim();
+    if (!trimmed) {
+        return null;
+    }
+    if (trimmed.startsWith(NODE_PROTOCOL_PREFIX) ||
+        trimmed.startsWith(HTTP_PROTOCOL_PREFIX) ||
+        trimmed.startsWith(HTTPS_PROTOCOL_PREFIX)) {
+        return null;
+    }
+    if (trimmed.startsWith(RELATIVE_PATH_PREFIX)) {
+        return trimmed
+            .slice(RELATIVE_PATH_PREFIX.length)
+            .replaceAll(WINDOWS_PATH_SEPARATOR, POSIX_PATH_SEPARATOR);
+    }
+    if (trimmed.startsWith(PARENT_RELATIVE_PREFIX) || trimmed.includes(POSIX_PATH_SEPARATOR)) {
+        return trimmed.replaceAll(WINDOWS_PATH_SEPARATOR, POSIX_PATH_SEPARATOR);
+    }
+    return null;
+}
+/**
+ * Normalize packed tarball paths across npm/pnpm variants.
+ *
+ * Some pack tools emit "package/dist/index.js" while others emit "dist/index.js".
+ * Contract comparisons use package-relative paths, so strip the optional prefix.
+ */
+function normalizePackedPath(filePath) {
+    const normalized = normalizeManifestPath(filePath);
+    if (!normalized) {
+        return null;
+    }
+    if (normalized.startsWith(PACK_TOOL_PACKAGE_PREFIX)) {
+        return normalized.slice(PACK_TOOL_PACKAGE_PREFIX.length);
+    }
+    return normalized;
+}
+function buildDistCountMismatchError(distFileCount, srcFileCount) {
+    return `${DIST_BUILD_INCOMPLETE_PREFIX} (${distFileCount} < ${srcFileCount}), ${DIST_BUILD_INCOMPLETE_SUFFIX}`;
+}
+function buildPackBaselineThresholdError(packedFileCount, previousPackedFileCount) {
+    return `${PACK_COUNT_BELOW_BASELINE_PREFIX} ${packedFileCount} ${PACK_COUNT_BELOW_BASELINE_MID} (${previousPackedFileCount})`;
+}
+function buildSkipBuildSymlinkError(relativeDistPath) {
+    return (`${SKIP_BUILD_SYMLINK_ERROR_PREFIX} ${relativeDistPath} is a symlink.\n` +
+        `${SKIP_BUILD_SYMLINK_ERROR_GUIDANCE}`);
+}
+function buildWorkspacePackDryRunCommand(packageName) {
+    return `${PKG_MANAGER} --filter "${packageName}" pack --json --dry-run`;
+}
+function buildLatestPublishedPackDryRunCommand(packageName) {
+    return `npm pack "${packageName}@latest" --json --dry-run`;
+}
+/**
+ * Collect all string leaf values from nested export conditions.
+ */
+function collectLeafStringValues(value, collector) {
+    if (typeof value === 'string') {
+        collector.push(value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value) {
+            collectLeafStringValues(entry, collector);
+        }
+        return;
+    }
+    if (value && typeof value === 'object') {
+        for (const entry of Object.values(value)) {
+            collectLeafStringValues(entry, collector);
+        }
+    }
+}
+/**
+ * Derive package-file contract paths from package.json fields.
+ *
+ * Contract source of truth:
+ * - exports map (all subpath leaf values)
+ * - main/types
+ * - bin targets
+ */
+export function extractPackageContractPaths(manifest) {
+    const rawPaths = [];
+    if (typeof manifest.main === 'string') {
+        rawPaths.push(manifest.main);
+    }
+    if (typeof manifest.types === 'string') {
+        rawPaths.push(manifest.types);
+    }
+    if (typeof manifest.bin === 'string') {
+        rawPaths.push(manifest.bin);
+    }
+    else if (manifest.bin && typeof manifest.bin === 'object') {
+        rawPaths.push(...Object.values(manifest.bin));
+    }
+    if (manifest.exports !== undefined) {
+        collectLeafStringValues(manifest.exports, rawPaths);
+    }
+    const deduped = new Set();
+    for (const rawPath of rawPaths) {
+        const normalized = normalizeManifestPath(rawPath);
+        if (normalized) {
+            deduped.add(normalized);
+        }
+    }
+    return [...deduped];
+}
+/**
+ * Determine if this package publishes dist artifacts.
+ */
+function packageExpectsDist(manifest, contractPaths) {
+    const files = manifest.files ?? [];
+    const includesDistInFiles = files.some((entry) => {
+        const normalized = entry
+            .trim()
+            .replaceAll(WINDOWS_PATH_SEPARATOR, POSIX_PATH_SEPARATOR)
+            .replace(/\/+$/, '');
+        return normalized === DIST_DIR_NAME || normalized.startsWith(`${DIST_DIR_NAME}/`);
+    });
+    return (includesDistInFiles || contractPaths.some((entry) => entry.startsWith(`${DIST_DIR_NAME}/`)));
+}
+/**
+ * Count files recursively for sanity checks.
+ */
+function countFilesRecursive(pathToCount) {
+    if (!existsSync(pathToCount)) {
+        return 0;
+    }
+    const stat = lstatSync(pathToCount);
+    if (!stat.isDirectory()) {
+        return 0;
+    }
+    let fileCount = 0;
+    const entries = readdirSync(pathToCount, { withFileTypes: true });
+    for (const entry of entries) {
+        const absolutePath = join(pathToCount, entry.name);
+        if (entry.isDirectory()) {
+            fileCount += countFilesRecursive(absolutePath);
+        }
+        else if (entry.isFile()) {
+            fileCount += 1;
+        }
+    }
+    return fileCount;
+}
+/**
+ * Validate packed artifacts against package contract paths and dynamic sanity checks.
+ */
+export function validatePackedArtifacts(input) {
+    const contractPaths = extractPackageContractPaths(input.manifest);
+    const normalizedPackedFiles = input.packedFiles
+        .map((entry) => normalizePackedPath(entry))
+        .filter((entry) => entry !== null);
+    const packedSet = new Set(normalizedPackedFiles);
+    const missingContractPaths = contractPaths.filter((entry) => !packedSet.has(entry));
+    const errors = [];
+    if (input.packedFiles.length === 0) {
+        errors.push(PACK_ZERO_FILES_ERROR);
+    }
+    if (missingContractPaths.length > 0) {
+        errors.push(`${MISSING_CONTRACT_PREFIX}${missingContractPaths.join(', ')}`);
+    }
+    const expectsDist = packageExpectsDist(input.manifest, contractPaths);
+    if (expectsDist) {
+        if (input.distFileCount === 0) {
+            errors.push(DIST_EMPTY_ERROR);
+        }
+        else if (input.srcFileCount > 0 && input.distFileCount < input.srcFileCount) {
+            errors.push(buildDistCountMismatchError(input.distFileCount, input.srcFileCount));
+        }
+    }
+    if (input.previousPackedFileCount !== undefined && input.previousPackedFileCount > 0) {
+        const minimumExpected = Math.max(1, Math.ceil(input.previousPackedFileCount * PREVIOUS_PACK_MIN_RATIO));
+        if (input.packedFiles.length < minimumExpected) {
+            errors.push(buildPackBaselineThresholdError(input.packedFiles.length, input.previousPackedFileCount));
+        }
+    }
+    return {
+        ok: errors.length === 0,
+        packageName: input.packageName,
+        contractPaths,
+        missingContractPaths,
+        errors,
+    };
+}
+/**
+ * Replace symlinked dist directories with real directories.
+ *
+ * This avoids npm pack/publish inconsistencies from cross-worktree dist symlinks.
+ */
+export function ensureDistPathsMaterialized(packageDirs, options = {}) {
+    const { skipBuild = false, dryRun = false } = options;
+    let checkedCount = 0;
+    let materializedCount = 0;
+    for (const packageDir of packageDirs) {
+        const distPath = join(packageDir, DIST_DIR_NAME);
+        if (!existsSync(distPath)) {
+            continue;
+        }
+        const distStat = lstatSync(distPath);
+        if (!distStat.isSymbolicLink()) {
+            continue;
+        }
+        checkedCount += 1;
+        const relativeDistPath = distPath.replace(`${process.cwd()}/`, '');
+        if (skipBuild) {
+            die(buildSkipBuildSymlinkError(relativeDistPath));
+        }
+        if (dryRun) {
+            console.log(`${LOG_PREFIX} [${PRE_FLIGHT_LABEL}] Would materialize symlinked dist at ${relativeDistPath}`);
+            continue;
+        }
+        rmSync(distPath, { recursive: true, force: true });
+        mkdirSync(distPath, { recursive: true });
+        materializedCount += 1;
+        console.log(`${LOG_PREFIX} [${PRE_FLIGHT_LABEL}] Materialized symlinked dist at ${relativeDistPath}`);
+    }
+    return { checkedCount, materializedCount };
+}
 /**
  * Build commit message for version bump
  *
@@ -186,16 +467,6 @@ export function buildCommitMessage(version) {
 export function buildTagName(version) {
     return `v${version}`;
 }
-/**
- * Get relative path from worktree root
- *
- * @param absolutePath - Absolute file path
- * @param worktreePath - Worktree root path
- * @returns Relative path
- */
-function getRelativePath(absolutePath, worktreePath) {
-    return absolutePath.replace(worktreePath + '/', '');
-}
 /**
  * Execute a shell command and handle errors
  *
@@ -221,6 +492,188 @@ function runCommand(cmd, options = {}) {
         throw new Error(`Command failed: ${cmd}`, { cause: error });
     }
 }
+/**
+ * Execute a shell command and capture stdout.
+ */
+function runCommandCapture(cmd, options = {}) {
+    const { cwd = process.cwd(), label } = options;
+    const prefix = label ? `[${label}] ` : '';
+    console.log(`${LOG_PREFIX} ${prefix}Running: ${cmd}`);
+    try {
+        return execSync(cmd, {
+            cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            encoding: FILE_SYSTEM.ENCODING,
+        });
+    }
+    catch (error) {
+        throw new Error(`Command failed: ${cmd}`, { cause: error });
+    }
+}
+/** Characters that can start a valid JSON value from pack commands */
+const JSON_ARRAY_START = '[';
+const JSON_OBJECT_START = '{';
+/**
+ * Find the index of the first real JSON-start sequence in a string.
+ *
+ * pnpm lifecycle scripts can prepend non-JSON output to stdout before the
+ * actual JSON payload — including log-style brackets like `[sync:bundled-packs]`.
+ * A bare `[` is ambiguous, so this function peeks at the next non-whitespace
+ * character to distinguish JSON arrays (`[{`, `["`, `[]`) and objects (`{"`, `{}`)
+ * from log prefixes.
+ *
+ * WU-2062: Replaces naive indexOf('[') which matched log brackets.
+ *
+ * @returns Index of the first valid JSON start, or 0 if not found (let JSON.parse report the error)
+ */
+export function findJsonStartIndex(raw) {
+    for (let i = 0; i < raw.length; i++) {
+        const ch = raw[i];
+        if (ch !== JSON_ARRAY_START && ch !== JSON_OBJECT_START) {
+            continue;
+        }
+        // Peek past optional whitespace to verify this starts a JSON value,
+        // not a log-style bracket like [sync:bundled-packs].
+        let j = i + 1;
+        while (j < raw.length &&
+            (raw[j] === ' ' || raw[j] === '\t' || raw[j] === '\n' || raw[j] === '\r')) {
+            j++;
+        }
+        if (j >= raw.length) {
+            return i;
+        }
+        const next = raw[j];
+        // Valid JSON array starts: [{ , [" , [] (empty)
+        if (ch === JSON_ARRAY_START && (next === JSON_OBJECT_START || next === '"' || next === ']')) {
+            return i;
+        }
+        // Valid JSON object starts: {" , {} (empty)
+        if (ch === JSON_OBJECT_START && (next === '"' || next === '}')) {
+            return i;
+        }
+    }
+    // Not found — return 0 so JSON.parse reports the actual error
+    return 0;
+}
+/**
+ * Parse JSON output from npm/pnpm pack dry runs.
+ *
+ * pnpm lifecycle scripts (prepack/postpack) can emit non-JSON text to stdout
+ * before the actual JSON payload. This function strips such prefix noise by
+ * locating the first `[` or `{` character — the start of valid JSON.
+ */
+export function parsePackDryRunMetadata(rawOutput) {
+    const trimmed = rawOutput.trim();
+    if (!trimmed) {
+        throw new Error(PACK_EMPTY_OUTPUT_ERROR);
+    }
+    // pnpm lifecycle scripts (prepack/postpack) can emit text to stdout before
+    // the JSON payload. Strip everything before the first JSON-start character.
+    const jsonStartIndex = findJsonStartIndex(trimmed);
+    const jsonPayload = jsonStartIndex > 0 ? trimmed.slice(jsonStartIndex) : trimmed;
+    const parsed = JSON.parse(jsonPayload);
+    const normalized = Array.isArray(parsed) ? parsed[0] : parsed;
+    if (!normalized || typeof normalized !== 'object') {
+        throw new Error(PACK_INVALID_JSON_ERROR);
+    }
+    const files = normalized.files;
+    if (!Array.isArray(files)) {
+        throw new Error(PACK_MISSING_FILES_ARRAY_ERROR);
+    }
+    for (const file of files) {
+        if (!file ||
+            typeof file !== 'object' ||
+            typeof file.path !== 'string') {
+            throw new Error(PACK_INVALID_FILES_ENTRY_ERROR);
+        }
+    }
+    const entryCount = normalized.entryCount;
+    return {
+        files: files,
+        entryCount: typeof entryCount === 'number' ? entryCount : undefined,
+    };
+}
+/**
+ * Read package manifest for release validation.
+ */
+function readPackageManifest(packageJsonPath) {
+    return JSON.parse(readFileSync(packageJsonPath, {
+        encoding: FILE_SYSTEM.UTF8,
+    }));
+}
+/**
+ * Resolve packed file list for a workspace package via pnpm pack --dry-run.
+ */
+function getWorkspacePackedFiles(packageName) {
+    const output = runCommandCapture(buildWorkspacePackDryRunCommand(packageName), {
+        label: PACK_VALIDATE_LABEL,
+    });
+    const metadata = parsePackDryRunMetadata(output);
+    return metadata.files
+        .map((entry) => normalizePackedPath(entry.path))
+        .filter((entry) => entry !== null);
+}
+/**
+ * Resolve packed file count for the currently published npm version.
+ */
+function getPreviousPublishedPackFileCount(packageName) {
+    try {
+        const output = runCommandCapture(buildLatestPublishedPackDryRunCommand(packageName), {
+            label: PACK_BASELINE_LABEL,
+        });
+        const metadata = parsePackDryRunMetadata(output);
+        const entryCount = metadata.entryCount;
+        if (typeof entryCount === 'number') {
+            return entryCount;
+        }
+        return metadata.files.length;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`${LOG_PREFIX} [${PACK_BASELINE_LABEL}] Skipping previous-version count for ${packageName}: ${message}`);
+        return undefined;
+    }
+}
+/**
+ * Validate release package artifacts before tag/publish.
+ */
+function validateReleaseArtifactsForPublish(packageJsonPaths, dryRun) {
+    if (dryRun) {
+        console.log(`${LOG_PREFIX} [${PACK_VALIDATE_LABEL}] Would validate packed artifacts against package contracts`);
+        return;
+    }
+    const failures = [];
+    for (const packageJsonPath of packageJsonPaths) {
+        const packageDir = dirname(packageJsonPath);
+        const manifest = readPackageManifest(packageJsonPath);
+        const packageName = manifest.name ?? packageDir;
+        const packedFiles = getWorkspacePackedFiles(packageName);
+        const previousPackedFileCount = getPreviousPublishedPackFileCount(packageName);
+        const srcFileCount = countFilesRecursive(join(packageDir, SOURCE_DIR_NAME));
+        const distFileCount = countFilesRecursive(join(packageDir, DIST_DIR_NAME));
+        const result = validatePackedArtifacts({
+            packageName,
+            packageDir,
+            manifest,
+            packedFiles,
+            srcFileCount,
+            distFileCount,
+            previousPackedFileCount,
+        });
+        if (!result.ok) {
+            failures.push(result);
+        }
+    }
+    if (failures.length > 0) {
+        const details = failures
+            .map((failure) => `- ${failure.packageName}\n` + failure.errors.map((error) => `  - ${error}`).join('\n'))
+            .join('\n');
+        die(`${RELEASE_VALIDATION_FAILURE_HEADER}\n\n` +
+            `${details}\n\n` +
+            `${RELEASE_VALIDATION_FAILURE_FOOTER}`);
+    }
+    console.log(`${LOG_PREFIX} ✅ Packed artifact validation passed for ${packageJsonPaths.length} packages`);
+}
 /**
  * Check if npm authentication is available
  *
@@ -313,6 +766,63 @@ export async function pushTagWithForce(git, tagName, reason = 'release: tag push
         }
     }
 }
+/**
+ * Clean up release artifacts after a failed release attempt.
+ *
+ * WU-2062: Ensures main is never left dirty by a failed release. Handles:
+ * 1. Materialized dist directories (symlinks replaced with real dirs by preflight)
+ * 2. Generated packs/ directories (from prepack lifecycle scripts)
+ * 3. Version-bumped package.json files (from Phase 2)
+ *
+ * After cleanup, all tracked files are restored to HEAD state and untracked
+ * generated files are removed.
+ */
+async function cleanupFailedRelease(packageDirs) {
+    console.error(`\n${LOG_PREFIX} ⚠️  Release failed — cleaning up artifacts on main...`);
+    try {
+        // 1. Remove materialized dist directories so git can restore symlinks.
+        //    ensureDistPathsMaterialized replaces symlinks with real dirs; build fills
+        //    them with untracked output. Must delete before git checkout can recreate
+        //    the tracked symlink.
+        for (const packageDir of packageDirs) {
+            const distPath = join(packageDir, DIST_DIR_NAME);
+            if (existsSync(distPath) && !lstatSync(distPath).isSymbolicLink()) {
+                rmSync(distPath, { recursive: true, force: true });
+            }
+        }
+        // 2. Remove untracked generated files (e.g., packs/ from prepack lifecycle scripts).
+        //    These are created by sync-bundled-packs.mjs during pack --dry-run but may not
+        //    be cleaned up if the release script fails before postpack runs.
+        for (const packageDir of packageDirs) {
+            const packsDir = join(packageDir, 'packs');
+            if (existsSync(packsDir)) {
+                rmSync(packsDir, { recursive: true, force: true });
+                const relativePath = packsDir.replace(`${process.cwd()}/`, '');
+                console.error(`${LOG_PREFIX}   Removed generated ${relativePath}`);
+            }
+        }
+        // 3. Restore all tracked files to HEAD state (dist symlinks + package.json versions).
+        //    Safe because assertWorkingTreeClean verified the tree was clean before we started.
+        const git = getGitForCwd();
+        await git.raw(['checkout', '--', '.']);
+        // 4. Reinstall dependencies to restore workspace symlinks.
+        //    WU-2063: git checkout -- . can change package.json files and dist symlinks,
+        //    which invalidates pnpm's link state. Running pnpm install ensures
+        //    workspace package links in node_modules/ are consistent.
+        console.error(`${LOG_PREFIX}   Restoring workspace links...`);
+        execFileSync(PKG_MANAGER, ['install'], {
+            cwd: process.cwd(),
+            stdio: 'inherit',
+            encoding: FILE_SYSTEM.ENCODING,
+        });
+        console.error(`${LOG_PREFIX} ✅ Cleanup complete — main is clean`);
+    }
+    catch (cleanupError) {
+        const message = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
+        console.error(`${LOG_PREFIX} ⚠️  Automatic cleanup failed: ${message}`);
+        console.error(`${LOG_PREFIX}   Manual recovery: git checkout -- . && git clean -fd`);
+    }
+}
 /**
  * Main release function
  * WU-1085: Renamed --version to --release-version to avoid conflict with CLI --version flag
@@ -345,13 +855,7 @@ export async function main() {
     const git = getGitForCwd();
     await ensureOnMain(git);
     // Check for uncommitted changes
-    const isClean = await git.isClean();
-    if (!isClean) {
-        die(`Working directory has uncommitted changes.\n\n` +
-            `Commit or stash changes before releasing:\n` +
-            `  git status\n` +
-            `  git stash  # or git commit`);
-    }
+    await assertWorkingTreeClean(git, RELEASE_CLEAN_CHECK_PHASE_BEFORE_RELEASE);
     // Find all @lumenflow/* packages to update
     const packagePaths = findPackageJsonPaths();
     if (packagePaths.length === 0) {
@@ -361,6 +865,7 @@ export async function main() {
     for (const p of packagePaths) {
         console.log(`  - ${p.replace(process.cwd() + '/', '')}`);
     }
+    const packageDirs = packagePaths.map((path) => dirname(path));
     // Check npm authentication for publish
     if (!skipPublish && !dryRun && !hasNpmAuth()) {
         die(`npm authentication not found.\n\n` +
@@ -370,102 +875,145 @@ export async function main() {
             `Get a token at: https://www.npmjs.com/settings/tokens\n` +
             `Or use --skip-publish to only bump versions and create tag.`);
     }
-    // Execute version bump in micro-worktree
-    if (dryRun) {
-        console.log(`${LOG_PREFIX} Would bump versions to ${version} using micro-worktree isolation`);
-        console.log(`${LOG_PREFIX} Would commit: ${buildCommitMessage(version)}`);
-    }
-    else {
-        console.log(`${LOG_PREFIX} Bumping versions using micro-worktree isolation...`);
-        // WU-1296: Use withReleaseEnv to set LUMENFLOW_WU_TOOL=release
-        // This allows the micro-worktree push to main without LUMENFLOW_FORCE
-        await withReleaseEnv(async () => {
-            await withMicroWorktree({
-                operation: OPERATION_NAME,
-                id: `v${version}`,
-                logPrefix: LOG_PREFIX,
-                execute: async ({ worktreePath }) => {
-                    // Check and exit changeset pre mode if active
-                    if (isInChangesetPreMode(worktreePath)) {
-                        console.log(`${LOG_PREFIX} Detected changeset pre-release mode, exiting...`);
-                        exitChangesetPreMode(worktreePath);
-                        console.log(`${LOG_PREFIX} ✅ Exited changeset pre mode`);
-                    }
-                    // Find package paths within the worktree
-                    const worktreePackagePaths = findPackageJsonPaths(worktreePath);
-                    // Update versions
-                    console.log(`${LOG_PREFIX} Updating ${worktreePackagePaths.length} package versions...`);
-                    await updatePackageVersions(worktreePackagePaths, version);
-                    // Get relative paths for commit
-                    const relativePaths = worktreePackagePaths.map((p) => getRelativePath(p, worktreePath));
-                    // If we exited pre mode, include the deleted pre.json in files to commit
-                    // (the deletion will be staged automatically by git add -A behavior)
-                    const _changesetPrePath = join(CHANGESET_DIR, CHANGESET_PRE_JSON);
-                    const filesToCommit = [...relativePaths];
-                    // Note: Deletion of pre.json is handled by git detecting the missing file
-                    console.log(`${LOG_PREFIX} ✅ Versions updated to ${version}`);
-                    return {
-                        commitMessage: buildCommitMessage(version),
-                        files: filesToCommit,
-                    };
-                },
-            });
-        });
-        console.log(`${LOG_PREFIX} ✅ Version bump committed and pushed`);
-    }
-    // Build packages
-    if (!skipBuild) {
-        runCommand(`${PKG_MANAGER} build`, { dryRun, label: 'build' });
-        console.log(`${LOG_PREFIX} ✅ Build complete`);
-    }
-    else {
-        console.log(`${LOG_PREFIX} Skipping build (--skip-build)`);
-    }
-    // Create git tag
-    const tagName = buildTagName(version);
-    if (dryRun) {
-        console.log(`${LOG_PREFIX} Would create tag: ${tagName}`);
-        console.log(`${LOG_PREFIX} Would push tag to ${REMOTES.ORIGIN}`);
-    }
-    else {
-        console.log(`${LOG_PREFIX} Creating tag ${tagName}...`);
-        await git.raw(['tag', '-a', tagName, '-m', `Release ${tagName}`]);
-        console.log(`${LOG_PREFIX} ✅ Tag created: ${tagName}`);
-        console.log(`${LOG_PREFIX} Pushing tag to ${REMOTES.ORIGIN}...`);
-        await pushTagWithForce(git, tagName, 'release: pushing version tag');
-        console.log(`${LOG_PREFIX} ✅ Tag pushed`);
-    }
-    // Publish to npm
-    if (!skipPublish) {
+    // Exit changeset pre mode if active
+    if (isInChangesetPreMode()) {
         if (dryRun) {
-            console.log(`${LOG_PREFIX} Would publish packages to npm`);
+            console.log(`${LOG_PREFIX} Would exit changeset pre-release mode`);
         }
         else {
-            console.log(`${LOG_PREFIX} Publishing packages to npm...`);
-            runCommand(`${PKG_MANAGER} -r publish --access public --no-git-checks`, { label: 'publish' });
-            console.log(`${LOG_PREFIX} ✅ Packages published to npm`);
+            console.log(`${LOG_PREFIX} Detected changeset pre-release mode, exiting...`);
+            exitChangesetPreMode();
+            console.log(`${LOG_PREFIX} ✅ Exited changeset pre mode`);
         }
     }
-    else {
-        console.log(`${LOG_PREFIX} Skipping npm publish (--skip-publish)`);
-    }
-    // Summary
-    console.log(`\n${LOG_PREFIX} 🎉 Release complete!`);
-    console.log(`${LOG_PREFIX} Version: ${version}`);
-    console.log(`${LOG_PREFIX} Tag: ${tagName}`);
-    if (!skipPublish && !dryRun) {
-        console.log(`${LOG_PREFIX} npm: https://www.npmjs.com/org/lumenflow`);
-    }
-    console.log(`\n${LOG_PREFIX} Next steps:`);
-    if (dryRun) {
-        console.log(`  - Run without --dry-run to execute the release`);
+    // WU-2062: Wrap all release phases in try/finally to ensure main is never
+    // left dirty. If anything fails before npm publish, cleanup restores main
+    // to its pre-release state. If npm publish succeeded but git push failed,
+    // we print manual recovery instructions instead of undoing the publish.
+    let npmPublished = false;
+    let releaseComplete = false;
+    try {
+        // ── Phase 1: Build & Validate (no writes to origin) ────────────────
+        // WU-2061: Build and validate BEFORE bumping versions or pushing anything.
+        // If any step here fails, main is untouched.
+        // Materialize symlinked dist directories for reliable pack/publish
+        const distPreparation = ensureDistPathsMaterialized(packageDirs, { skipBuild, dryRun });
+        if (distPreparation.checkedCount > 0 && !dryRun && distPreparation.materializedCount > 0) {
+            console.log(`${LOG_PREFIX} [${PRE_FLIGHT_LABEL}] Materialized ${distPreparation.materializedCount} symlinked dist directories`);
+        }
+        if (!skipBuild) {
+            runCommand(`${PKG_MANAGER} build`, { dryRun, label: 'build' });
+            console.log(`${LOG_PREFIX} ✅ Build complete`);
+        }
+        else {
+            console.log(`${LOG_PREFIX} Skipping build (--skip-build)`);
+        }
+        if (!skipPublish) {
+            validateReleaseArtifactsForPublish(packagePaths, Boolean(dryRun));
+        }
+        else if (dryRun) {
+            console.log(`${LOG_PREFIX} [${PACK_VALIDATE_LABEL}] Would skip artifact validation (--skip-publish)`);
+        }
+        // ── Phase 2: Version bump (local only, no push yet) ────────────────
+        // WU-2061: Bump versions locally on main. No micro-worktree needed — if
+        // anything fails after this, cleanup restores package.json files.
+        console.log(`${LOG_PREFIX} Bumping versions to ${version}...`);
+        if (dryRun) {
+            console.log(`${LOG_PREFIX} Would update ${packagePaths.length} package versions`);
+            console.log(`${LOG_PREFIX} Would commit: ${buildCommitMessage(version)}`);
+        }
+        else {
+            await updatePackageVersions(packagePaths, version);
+            console.log(`${LOG_PREFIX} ✅ Versions updated to ${version}`);
+        }
+        // ── Phase 3: Publish to npm ────────────────────────────────────────
+        // Publish BEFORE committing to git. If publish fails, cleanup restores
+        // package.json files and main stays clean.
+        if (!skipPublish) {
+            if (dryRun) {
+                console.log(`${LOG_PREFIX} Would publish packages to npm`);
+            }
+            else {
+                console.log(`${LOG_PREFIX} Publishing packages to npm...`);
+                runCommand(`${PKG_MANAGER} -r publish --access public --no-git-checks`, {
+                    label: 'publish',
+                });
+                npmPublished = true;
+                console.log(`${LOG_PREFIX} ✅ Packages published to npm`);
+            }
+        }
+        else {
+            console.log(`${LOG_PREFIX} Skipping npm publish (--skip-publish)`);
+        }
+        // ── Phase 4: Commit, tag, push (only after everything succeeds) ────
+        // WU-2061: This is the point of no return. Build passed, validation
+        // passed, npm publish succeeded. Now commit the version bump to main.
+        const tagName = buildTagName(version);
+        if (dryRun) {
+            console.log(`${LOG_PREFIX} Would commit: ${buildCommitMessage(version)}`);
+            console.log(`${LOG_PREFIX} Would create tag: ${tagName}`);
+            console.log(`${LOG_PREFIX} Would push to ${REMOTES.ORIGIN}`);
+        }
+        else {
+            // Format changed files before committing
+            const relativePaths = packagePaths.map((p) => p.replace(process.cwd() + '/', ''));
+            runCommand(`${PKG_MANAGER} prettier --write ${relativePaths.join(' ')}`, {
+                label: 'format',
+            });
+            // Stage and commit
+            await git.add(relativePaths);
+            await git.commit(buildCommitMessage(version));
+            console.log(`${LOG_PREFIX} ✅ Committed: ${buildCommitMessage(version)}`);
+            // Create and push tag
+            console.log(`${LOG_PREFIX} Creating tag ${tagName}...`);
+            await git.raw(['tag', '-a', tagName, '-m', `Release ${tagName}`]);
+            console.log(`${LOG_PREFIX} ✅ Tag created: ${tagName}`);
+            // Push commit + tag together
+            console.log(`${LOG_PREFIX} Pushing to ${REMOTES.ORIGIN}...`);
+            await withReleaseEnv(async () => {
+                await git.push(REMOTES.ORIGIN, 'main');
+                await git.push(REMOTES.ORIGIN, tagName);
+            });
+            console.log(`${LOG_PREFIX} ✅ Pushed to ${REMOTES.ORIGIN}`);
+        }
+        releaseComplete = true;
+        // Summary
+        console.log(`\n${LOG_PREFIX} 🎉 Release complete!`);
+        console.log(`${LOG_PREFIX} Version: ${version}`);
+        console.log(`${LOG_PREFIX} Tag: ${tagName}`);
+        if (!skipPublish && !dryRun) {
+            console.log(`${LOG_PREFIX} npm: https://www.npmjs.com/org/lumenflow`);
+        }
+        console.log(`\n${LOG_PREFIX} Next steps:`);
+        if (dryRun) {
+            console.log(`  - Run without --dry-run to execute the release`);
+        }
+        else {
+            console.log(`  - Create GitHub release: gh release create ${tagName} --title "Release ${tagName}"`);
+            if (skipPublish) {
+                console.log(`  - Publish to npm: ${PKG_MANAGER} -r publish --access public --no-git-checks`);
+            }
+            console.log(`  - Verify packages: npm view @lumenflow/cli version`);
+        }
     }
-    else {
-        console.log(`  - Create GitHub release: gh release create ${tagName} --title "Release ${tagName}"`);
-        if (skipPublish) {
-            console.log(`  - Publish to npm: ${PKG_MANAGER} -r publish --access public --no-git-checks`);
+    finally {
+        // WU-2062: Cleanup on failure — never leave main dirty
+        if (!releaseComplete && !dryRun) {
+            if (!npmPublished) {
+                // Nothing reached npm — safe to fully restore main
+                await cleanupFailedRelease(packageDirs);
+            }
+            else {
+                // npm packages are published but git commit/push failed.
+                // Do NOT undo the version bump — the published packages reference this version.
+                console.error(`\n${LOG_PREFIX} ⚠️  npm publish succeeded but git commit/push failed.`);
+                console.error(`${LOG_PREFIX}   The version bump is still in your working tree.`);
+                console.error(`${LOG_PREFIX}   To complete manually:`);
+                console.error(`${LOG_PREFIX}     git add -A && git commit -m "${buildCommitMessage(version)}"`);
+                console.error(`${LOG_PREFIX}     git tag -a ${buildTagName(version)} -m "Release ${buildTagName(version)}"`);
+                console.error(`${LOG_PREFIX}     LUMENFLOW_WU_TOOL=release git push origin main ${buildTagName(version)}`);
+            }
         }
-        console.log(`  - Verify packages: npm view @lumenflow/cli version`);
     }
 }
 // Guard main() for testability