@workflow/builders 4.0.1-beta.5 → 4.0.1-beta.51

package/dist/base-builder.js

@@ -1,15 +1,20 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, join, relative, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, realpath, rename, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { promisify } from 'node:util';
+import { pluralize, usesVercelWorld } from '@workflow/utils';
 import chalk from 'chalk';
-import { parse } from 'comment-json';
 import enhancedResolveOriginal from 'enhanced-resolve';
 import * as esbuild from 'esbuild';
 import { findUp } from 'find-up';
 import { glob } from 'tinyglobby';
+import { applySwcTransform, } from './apply-swc-transform.js';
 import { createDiscoverEntriesPlugin } from './discover-entries-esbuild-plugin.js';
+import { getImportPath } from './module-specifier.js';
 import { createNodeModuleErrorPlugin } from './node-module-esbuild-plugin.js';
+import { createPseudoPackagePlugin } from './pseudo-package-esbuild-plugin.js';
 import { createSwcPlugin } from './swc-esbuild-plugin.js';
+import { extractWorkflowGraphs } from './workflows-extractor.js';
 const enhancedResolve = promisify(enhancedResolveOriginal);
 const EMIT_SOURCEMAPS_FOR_DEBUGGING = process.env.WORKFLOW_EMIT_SOURCEMAPS_FOR_DEBUGGING === '1';
 /**
@@ -24,34 +29,39 @@ export class BaseBuilder {
         this.config = config;
     }
     /**
-     * Extracts TypeScript path mappings and baseUrl from tsconfig.json/jsconfig.json.
-     * Used to properly resolve module imports during bundling.
+     * Whether informational BaseBuilder logs should be printed.
+     * Subclasses can override this to silence progress logs while keeping warnings/errors.
      */
-    async getTsConfigOptions() {
-        const options = {};
-        const cwd = this.config.workingDir || process.cwd();
-        const tsJsConfig = await findUp(['tsconfig.json', 'jsconfig.json'], {
-            cwd,
-        });
-        if (tsJsConfig) {
-            try {
-                const rawJson = await readFile(tsJsConfig, 'utf8');
-                const parsed = parse(rawJson);
-                if (parsed) {
-                    options.paths = parsed.compilerOptions?.paths;
-                    if (parsed.compilerOptions?.baseUrl) {
-                        options.baseUrl = resolve(cwd, parsed.compilerOptions.baseUrl);
-                    }
-                    else {
-                        options.baseUrl = cwd;
-                    }
-                }
-            }
-            catch (err) {
-                console.error(`Failed to parse ${tsJsConfig} aliases might not apply properly`, err);
-            }
+    get shouldLogBaseBuilderInfo() {
+        return true;
+    }
+    logBaseBuilderInfo(...args) {
+        if (this.shouldLogBaseBuilderInfo) {
+            console.log(...args);
+        }
+    }
+    logCreateWorkflowsBundleInfo(...args) {
+        if (!this.config.suppressCreateWorkflowsBundleLogs) {
+            this.logBaseBuilderInfo(...args);
+        }
+    }
+    logCreateWebhookBundleInfo(...args) {
+        if (!this.config.suppressCreateWebhookBundleLogs) {
+            this.logBaseBuilderInfo(...args);
+        }
+    }
+    logCreateManifestInfo(...args) {
+        if (!this.config.suppressCreateManifestLogs) {
+            this.logBaseBuilderInfo(...args);
         }
-        return options;
+    }
+    /**
+     * Finds tsconfig.json/jsconfig.json for the project.
+     * Used by esbuild to properly resolve module imports during bundling.
+     */
+    async findTsConfigPath() {
+        const cwd = this.config.workingDir || process.cwd();
+        return findUp(['tsconfig.json', 'jsconfig.json'], { cwd });
     }
     /**
      * Discovers all source files in the configured directories.
@@ -73,6 +83,7 @@ export class BaseBuilder {
                 '**/.vercel/**',
                 '**/.workflow-data/**',
                 '**/.well-known/workflow/**',
+                '**/.svelte-kit/**',
             ],
             absolute: true,
         });
@@ -93,6 +104,7 @@ export class BaseBuilder {
         const state = {
             discoveredSteps: [],
             discoveredWorkflows: [],
+            discoveredSerdeFiles: [],
         };
         const discoverStart = Date.now();
         try {
@@ -104,30 +116,51 @@ export class BaseBuilder {
                 write: false,
                 outdir,
                 bundle: true,
-                sourcemap: EMIT_SOURCEMAPS_FOR_DEBUGGING,
+                sourcemap: false,
                 absWorkingDir: this.config.workingDir,
                 logLevel: 'silent',
+                // External packages that should not be bundled during discovery
+                external: this.config.externalPackages || [],
             });
         }
         catch (_) { }
-        console.log(`Discovering workflow directives`, `${Date.now() - discoverStart}ms`);
+        this.logBaseBuilderInfo(`Discovering workflow directives`, `${Date.now() - discoverStart}ms`);
         this.discoveredEntries.set(inputs, state);
         return state;
     }
     /**
      * Writes debug information to a JSON file for troubleshooting build issues.
-     * Executes whenever called, regardless of environment variables.
+     * Uses atomic write (temp file + rename) to prevent race conditions when
+     * multiple builds run concurrently.
      */
     async writeDebugFile(outfile, debugData, merge) {
+        const prefix = this.config.debugFilePrefix || '';
+        const targetPath = `${dirname(outfile)}/${prefix}${basename(outfile)}.debug.json`;
+        let existing = {};
         try {
-            let existing = {};
             if (merge) {
-                existing = JSON.parse(await readFile(`${outfile}.debug.json`, 'utf8').catch(() => '{}'));
+                try {
+                    const content = await readFile(targetPath, 'utf8');
+                    existing = JSON.parse(content);
+                }
+                catch (e) {
+                    // File doesn't exist yet or is corrupted - start fresh.
+                    // Don't log error for ENOENT (file not found) as that's expected on first run.
+                    if (e.code !== 'ENOENT') {
+                        console.warn('Error reading debug file, starting fresh:', e);
+                    }
+                }
             }
-            await writeFile(`${outfile}.debug.json`, JSON.stringify({
+            const mergedData = JSON.stringify({
                 ...existing,
                 ...debugData,
-            }, null, 2));
+            }, null, 2);
+            // Write atomically: write to temp file, then rename.
+            // rename() is atomic on POSIX systems and provides best-effort atomicity on Windows.
+            // Prevents race conditions where concurrent builds read partially-written files.
+            const tempPath = `${targetPath}.${randomUUID()}.tmp`;
+            await writeFile(tempPath, mergedData);
+            await rename(tempPath, targetPath);
         }
         catch (error) {
             console.warn('Failed to write debug file:', error);
@@ -137,7 +170,7 @@ export class BaseBuilder {
      * Logs and optionally throws on esbuild errors and warnings.
      * @param throwOnError - If true, throws an error when esbuild errors are present
      */
-    logEsbuildMessages(result, phase, throwOnError = true) {
+    logEsbuildMessages(result, phase, throwOnError = true, options) {
         if (result.errors && result.errors.length > 0) {
             console.error(`❌ esbuild errors in ${phase}:`);
             const errorMessages = [];
@@ -154,7 +187,9 @@ export class BaseBuilder {
                 throw new Error(`Build failed during ${phase}:\n${errorMessages.join('\n')}`);
             }
         }
-        if (result.warnings && result.warnings.length > 0) {
+        if (!options?.suppressWarnings &&
+            result.warnings &&
+            result.warnings.length > 0) {
             console.warn(`!  esbuild warnings in ${phase}:`);
             for (const warning of result.warnings) {
                 console.warn(`  ${warning.text}`);
@@ -164,18 +199,48 @@ export class BaseBuilder {
             }
         }
     }
+    /**
+     * Converts an absolute file path to a normalized relative path for the manifest.
+     */
+    getRelativeFilepath(absolutePath) {
+        const normalizedFile = absolutePath.replace(/\\/g, '/');
+        const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');
+        let relativePath = relative(normalizedWorkingDir, normalizedFile).replace(/\\/g, '/');
+        // Handle files discovered outside the working directory
+        if (relativePath.startsWith('../')) {
+            relativePath = relativePath
+                .split('/')
+                .filter((part) => part !== '..')
+                .join('/');
+        }
+        return relativePath;
+    }
     /**
      * Creates a bundle for workflow step functions.
      * Steps have full Node.js runtime access and handle side effects, API calls, etc.
      *
      * @param externalizeNonSteps - If true, only bundles step entry points and externalizes other code
+     * @returns Build context (for watch mode) and the collected workflow manifest
      */
-    async createStepsBundle({ inputFiles, format = 'cjs', outfile, externalizeNonSteps, tsBaseUrl, tsPaths, }) {
+    async createStepsBundle({ inputFiles, format = 'cjs', outfile, externalizeNonSteps, tsconfigPath, discoveredEntries, }) {
         // These need to handle watching for dev to scan for
         // new entries and changes to existing ones
-        const { discoveredSteps: stepFiles } = await this.discoverEntries(inputFiles, dirname(outfile));
+        const discovered = discoveredEntries ??
+            (await this.discoverEntries(inputFiles, dirname(outfile)));
+        const stepFiles = [...discovered.discoveredSteps].sort();
+        const workflowFiles = [...discovered.discoveredWorkflows].sort();
+        const serdeFiles = [...discovered.discoveredSerdeFiles].sort();
+        // Include serde files that aren't already step files for cross-context class registration.
+        // Classes need to be registered in the step bundle so they can be deserialized
+        // when receiving data from workflows and serialized when returning data to workflows.
+        const stepFilesSet = new Set(stepFiles);
+        const serdeOnlyFiles = serdeFiles.filter((f) => !stepFilesSet.has(f));
         // log the step files for debugging
-        await this.writeDebugFile(outfile, { stepFiles });
+        await this.writeDebugFile(outfile, {
+            stepFiles,
+            workflowFiles,
+            serdeOnlyFiles,
+        });
         const stepsBundleStart = Date.now();
         const workflowManifest = {};
         const builtInSteps = 'workflow/internal/builtins';
@@ -187,10 +252,16 @@ export class BaseBuilder {
                 `Caused by: ${chalk.red(String(err))}`,
             ].join('\n'));
         });
-        // Create a virtual entry that imports all files. All step definitions
-        // will get registered thanks to the swc transform.
-        const imports = stepFiles
-            .map((file) => {
+        // Helper to create import statement from file path
+        // For workspace/node_modules packages, uses the package name so esbuild
+        // will resolve through package.json exports with the appropriate conditions
+        const createImport = (file) => {
+            const { importPath, isPackage } = getImportPath(file, this.config.workingDir);
+            if (isPackage) {
+                // Use package name - esbuild will resolve via package.json exports
+                return `import '${importPath}';`;
+            }
+            // Local app file - use relative path
             // Normalize both paths to forward slashes before calling relative()
             // This is critical on Windows where relative() can produce unexpected results with mixed path formats
             const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');
@@ -202,16 +273,37 @@ export class BaseBuilder {
                 relativePath = `./${relativePath}`;
             }
             return `import '${relativePath}';`;
-        })
-            .join('\n');
+        };
+        // Create a virtual entry that imports all files. All step definitions
+        // will get registered thanks to the swc transform.
+        const stepImports = stepFiles.map(createImport).join('\n');
+        // Include serde-only files for class registration side effects
+        const serdeImports = serdeOnlyFiles.map(createImport).join('\n');
         const entryContent = `
     // Built in steps
     import '${builtInSteps}';
     // User steps
-    ${imports}
+    ${stepImports}
+    // Serde files for cross-context class registration
+    ${serdeImports}
     // API entrypoint
     export { stepEntrypoint as POST } from 'workflow/runtime';`;
         // Bundle with esbuild and our custom SWC plugin
+        const entriesToBundle = externalizeNonSteps
+            ? [
+                ...stepFiles,
+                ...serdeFiles,
+                ...(resolvedBuiltInSteps ? [resolvedBuiltInSteps] : []),
+            ]
+            : undefined;
+        const normalizedEntriesToBundle = entriesToBundle
+            ? Array.from(new Set((await Promise.all(entriesToBundle.map(async (entryToBundle) => {
+                const resolvedEntry = await realpath(entryToBundle).catch(() => undefined);
+                return resolvedEntry
+                    ? [entryToBundle, resolvedEntry]
+                    : [entryToBundle];
+            }))).flat()))
+            : undefined;
         const esbuildCtx = await esbuild.context({
             banner: {
                 js: '// biome-ignore-all lint: generated file\n/* eslint-disable */\n',
@@ -233,42 +325,71 @@ export class BaseBuilder {
             treeShaking: true,
             keepNames: true,
             minify: false,
-            resolveExtensions: ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'],
-            // TODO: investigate proper source map support
-            sourcemap: EMIT_SOURCEMAPS_FOR_DEBUGGING,
+            jsx: 'preserve',
+            logLevel: 'error',
+            // Use tsconfig for path alias resolution
+            tsconfig: tsconfigPath,
+            resolveExtensions: [
+                '.ts',
+                '.tsx',
+                '.mts',
+                '.cts',
+                '.js',
+                '.jsx',
+                '.mjs',
+                '.cjs',
+            ],
+            // Inline source maps for better stack traces in step execution.
+            // Steps execute in Node.js context and inline sourcemaps ensure we get
+            // meaningful stack traces with proper file names and line numbers when errors
+            // occur in deeply nested function calls across multiple files.
+            sourcemap: 'inline',
             plugins: [
+                // Handle pseudo-packages like 'server-only' and 'client-only' by providing
+                // empty modules. Must run first to intercept these before other resolution.
+                createPseudoPackagePlugin(),
                 createSwcPlugin({
                     mode: 'step',
-                    entriesToBundle: externalizeNonSteps
-                        ? [
-                            ...stepFiles,
-                            ...(resolvedBuiltInSteps ? [resolvedBuiltInSteps] : []),
-                        ]
-                        : undefined,
+                    entriesToBundle: normalizedEntriesToBundle,
                     outdir: outfile ? dirname(outfile) : undefined,
-                    tsBaseUrl,
-                    tsPaths,
                     workflowManifest,
                 }),
             ],
             // Plugin should catch most things, but this lets users hard override
             // if the plugin misses anything that should be externalized
-            external: this.config.externalPackages || [],
+            external: ['bun', 'bun:*', ...(this.config.externalPackages || [])],
         });
         const stepsResult = await esbuildCtx.rebuild();
         this.logEsbuildMessages(stepsResult, 'steps bundle creation');
-        console.log('Created steps bundle', `${Date.now() - stepsBundleStart}ms`);
-        const partialWorkflowManifest = {
-            steps: workflowManifest.steps,
-        };
-        // always write to debug file
-        await this.writeDebugFile(join(dirname(outfile), 'manifest'), partialWorkflowManifest, true);
+        this.logBaseBuilderInfo('Created steps bundle', `${Date.now() - stepsBundleStart}ms`);
+        // Handle workflow-only files that may have been tree-shaken from the bundle.
+        // These files have no steps, so esbuild removes them, but we still need their
+        // workflow metadata for the manifest. Transform them separately.
+        const workflowOnlyFiles = workflowFiles.filter((f) => !stepFiles.includes(f));
+        await Promise.all(workflowOnlyFiles.map(async (workflowFile) => {
+            try {
+                const source = await readFile(workflowFile, 'utf8');
+                const relativeFilepath = this.getRelativeFilepath(workflowFile);
+                const { workflowManifest: fileManifest } = await applySwcTransform(relativeFilepath, source, 'workflow');
+                if (fileManifest.workflows) {
+                    workflowManifest.workflows = Object.assign(workflowManifest.workflows || {}, fileManifest.workflows);
+                }
+                if (fileManifest.classes) {
+                    workflowManifest.classes = Object.assign(workflowManifest.classes || {}, fileManifest.classes);
+                }
+            }
+            catch (error) {
+                // Log warning but continue - don't fail build for workflow-only file issues
+                console.warn(`Warning: Failed to extract workflow metadata from ${workflowFile}:`, error instanceof Error ? error.message : String(error));
+            }
+        }));
         // Create .gitignore in .swc directory
         await this.createSwcGitignore();
         if (this.config.watch) {
-            return esbuildCtx;
+            return { context: esbuildCtx, manifest: workflowManifest };
         }
         await esbuildCtx.dispose();
+        return { context: undefined, manifest: workflowManifest };
     }
     /**
      * Creates a bundle for workflow orchestration functions.
@@ -276,28 +397,50 @@ export class BaseBuilder {
      *
      * @param bundleFinalOutput - If false, skips the final bundling step (used by Next.js)
      */
-    async createWorkflowsBundle({ inputFiles, format = 'cjs', outfile, bundleFinalOutput = true, tsBaseUrl, tsPaths, }) {
-        const { discoveredWorkflows: workflowFiles } = await this.discoverEntries(inputFiles, dirname(outfile));
+    async createWorkflowsBundle({ inputFiles, format = 'cjs', outfile, bundleFinalOutput = true, tsconfigPath, discoveredEntries, }) {
+        const discovered = discoveredEntries ??
+            (await this.discoverEntries(inputFiles, dirname(outfile)));
+        const workflowFiles = [...discovered.discoveredWorkflows].sort();
+        const serdeFiles = [...discovered.discoveredSerdeFiles].sort();
+        // Include serde files that aren't already workflow files for cross-context class registration.
+        // Classes need to be registered in the workflow bundle so they can be deserialized
+        // when receiving data from steps or when serializing data to send to steps.
+        const workflowFilesSet = new Set(workflowFiles);
+        const serdeOnlyFiles = serdeFiles.filter((f) => !workflowFilesSet.has(f));
         // log the workflow files for debugging
-        await this.writeDebugFile(outfile, { workflowFiles });
-        // Create a virtual entry that imports all files
-        const imports = `globalThis.__private_workflows = new Map();\n` +
-            workflowFiles
-                .map((file, workflowFileIdx) => {
-                // Normalize both paths to forward slashes before calling relative()
-                // This is critical on Windows where relative() can produce unexpected results with mixed path formats
-                const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');
-                const normalizedFile = file.replace(/\\/g, '/');
-                // Calculate relative path from working directory to the file
-                let relativePath = relative(normalizedWorkingDir, normalizedFile).replace(/\\/g, '/');
-                // Ensure relative paths start with ./ so esbuild resolves them correctly
-                if (!relativePath.startsWith('.')) {
-                    relativePath = `./${relativePath}`;
-                }
-                return `import * as workflowFile${workflowFileIdx} from '${relativePath}';
-            Object.values(workflowFile${workflowFileIdx}).map(item => item?.workflowId && globalThis.__private_workflows.set(item.workflowId, item))`;
-            })
-                .join('\n');
+        await this.writeDebugFile(outfile, { workflowFiles, serdeOnlyFiles });
+        // Helper to create import statement from file path
+        // For packages, uses the package name so esbuild will resolve through
+        // package.json exports with conditions: ['workflow']
+        const createImport = (file) => {
+            const { importPath, isPackage } = getImportPath(file, this.config.workingDir);
+            if (isPackage) {
+                // Use package name - esbuild will resolve via package.json exports
+                // and apply the 'workflow' condition
+                return `import '${importPath}';`;
+            }
+            // Local app file - use relative path
+            // Normalize both paths to forward slashes before calling relative()
+            // This is critical on Windows where relative() can produce unexpected results with mixed path formats
+            const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');
+            const normalizedFile = file.replace(/\\/g, '/');
+            // Calculate relative path from working directory to the file
+            let relativePath = relative(normalizedWorkingDir, normalizedFile).replace(/\\/g, '/');
+            // Ensure relative paths start with ./ so esbuild resolves them correctly
+            if (!relativePath.startsWith('.')) {
+                relativePath = `./${relativePath}`;
+            }
+            return `import '${relativePath}';`;
+        };
+        // Create a virtual entry that imports all workflow files
+        // The SWC plugin in workflow mode emits `globalThis.__private_workflows.set(workflowId, fn)`
+        // calls directly, so we just need to import the files (Map is initialized via banner)
+        const workflowImports = workflowFiles.map(createImport).join('\n');
+        // Include serde-only files for class registration side effects
+        const serdeImports = serdeOnlyFiles.map(createImport).join('\n');
+        const imports = serdeImports
+            ? `${workflowImports}\n// Serde files for cross-context class registration\n${serdeImports}`
+            : workflowImports;
         const bundleStartTime = Date.now();
         const workflowManifest = {};
         // Bundle with esbuild and our custom SWC plugin in workflow mode.
@@ -320,28 +463,54 @@ export class BaseBuilder {
             treeShaking: true,
             keepNames: true,
             minify: false,
-            // TODO: investigate proper source map support
-            sourcemap: EMIT_SOURCEMAPS_FOR_DEBUGGING,
-            resolveExtensions: ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'],
+            // Initialize the workflow registry at the very top of the bundle
+            // This must be in banner (not the virtual entry) because esbuild's bundling
+            // can reorder code, and the .set() calls need the Map to exist first
+            banner: {
+                js: 'globalThis.__private_workflows = new Map();',
+            },
+            // Inline source maps for better stack traces in workflow VM execution.
+            // This intermediate bundle is executed via runInContext() in a VM, so we need
+            // inline source maps to get meaningful stack traces instead of "evalmachine.<anonymous>".
+            sourcemap: 'inline',
+            // Use tsconfig for path alias resolution
+            tsconfig: tsconfigPath,
+            resolveExtensions: [
+                '.ts',
+                '.tsx',
+                '.mts',
+                '.cts',
+                '.js',
+                '.jsx',
+                '.mjs',
+                '.cjs',
+            ],
             plugins: [
+                // Handle pseudo-packages like 'server-only' and 'client-only' by providing
+                // empty modules. Must run first to intercept these before other resolution.
+                createPseudoPackagePlugin(),
                 createSwcPlugin({
                     mode: 'workflow',
-                    tsBaseUrl,
-                    tsPaths,
                     workflowManifest,
                 }),
                 // This plugin must run after the swc plugin to ensure dead code elimination
                 // happens first, preventing false positives on Node.js imports in unused code paths
                 createNodeModuleErrorPlugin(),
             ],
+            // NOTE: We intentionally do NOT use the external option here for workflow bundles.
+            // When packages are marked external with format: 'cjs', esbuild generates require() calls.
+            // However, the workflow VM (vm.runInContext) does not have require() defined - it only
+            // provides module.exports and exports. External packages would fail at runtime with:
+            //   ReferenceError: require is not defined
+            // Instead, we bundle everything and rely on:
+            // - createPseudoPackagePlugin() to handle server-only/client-only with empty modules
+            // - createNodeModuleErrorPlugin() to catch Node.js builtin imports at build time
         });
         const interimBundle = await interimBundleCtx.rebuild();
-        this.logEsbuildMessages(interimBundle, 'intermediate workflow bundle');
-        console.log('Created intermediate workflow bundle', `${Date.now() - bundleStartTime}ms`);
-        const partialWorkflowManifest = {
-            workflows: workflowManifest.workflows,
-        };
-        await this.writeDebugFile(join(dirname(outfile), 'manifest'), partialWorkflowManifest, true);
+        this.logEsbuildMessages(interimBundle, 'intermediate workflow bundle', true, {
+            suppressWarnings: this.config.suppressCreateWorkflowsBundleWarnings,
+        });
+        this.logCreateWorkflowsBundleInfo('Created intermediate workflow bundle', `${Date.now() - bundleStartTime}ms`);
         if (this.config.workflowManifestPath) {
             const resolvedPath = resolve(process.cwd(), this.config.workflowManifestPath);
             let prefix = '';
@@ -353,7 +522,7 @@ export class BaseBuilder {
                 prefix = 'export default ';
             }
             await mkdir(dirname(resolvedPath), { recursive: true });
-            await writeFile(resolvedPath, prefix + JSON.stringify(workflowManifest.workflows, null, 2));
+            await writeFile(resolvedPath, prefix + JSON.stringify(workflowManifest, null, 2));
         }
         // Create .gitignore in .swc directory
         await this.createSwcGitignore();
@@ -377,7 +546,11 @@ export const POST = workflowEntrypoint(workflowCode);`;
                 // Ensure the output directory exists
                 const outputDir = dirname(outfile);
                 await mkdir(outputDir, { recursive: true });
-                await writeFile(outfile, workflowFunctionCode);
+                // Atomic write: write to temp file then rename to prevent
+                // file watchers from reading partial file during write
+                const tempPath = `${outfile}.${randomUUID()}.tmp`;
+                await writeFile(tempPath, workflowFunctionCode);
+                await rename(tempPath, outfile);
                 return;
             }
             const bundleStartTime = Date.now();
@@ -394,7 +567,8 @@ export const POST = workflowEntrypoint(workflowCode);`;
                     loader: 'js',
                 },
                 outfile,
-                // TODO: investigate proper source map support
+                // Source maps for the final workflow bundle wrapper (not important since this code
+                // doesn't run in the VM - only the intermediate bundle sourcemap is relevant)
                 sourcemap: EMIT_SOURCEMAPS_FOR_DEBUGGING,
                 absWorkingDir: this.config.workingDir,
                 bundle: true,
@@ -406,17 +580,21 @@ export const POST = workflowEntrypoint(workflowCode);`;
                 minify: false,
                 external: ['@aws-sdk/credential-provider-web-identity'],
             });
-            this.logEsbuildMessages(finalWorkflowResult, 'final workflow bundle');
-            console.log('Created final workflow bundle', `${Date.now() - bundleStartTime}ms`);
+            this.logEsbuildMessages(finalWorkflowResult, 'final workflow bundle', true, {
+                suppressWarnings: this.config.suppressCreateWorkflowsBundleWarnings,
+            });
+            this.logCreateWorkflowsBundleInfo('Created final workflow bundle', `${Date.now() - bundleStartTime}ms`);
         };
         await bundleFinal(interimBundle.outputFiles[0].text);
         if (this.config.watch) {
             return {
+                manifest: workflowManifest,
                 interimBundleCtx,
                 bundleFinal,
             };
         }
         await interimBundleCtx.dispose();
+        return { manifest: workflowManifest };
     }
     /**
      * Creates a client library bundle for workflow execution.
@@ -428,23 +606,45 @@ export const POST = workflowEntrypoint(workflowCode);`;
             // Silently exit since no client bundle was requested
             return;
         }
-        console.log('Generating a client library at', this.config.clientBundlePath);
-        console.log('NOTE: The recommended way to use workflow with a framework like NextJS is using the loader/plugin with webpack/turbobpack/rollup');
+        this.logBaseBuilderInfo('Generating a client library at', this.config.clientBundlePath);
+        this.logBaseBuilderInfo('NOTE: The recommended way to use workflow with a framework like NextJS is using the loader/plugin with webpack/turbobpack/rollup');
         // Ensure we have the directory for the client bundle
         const outputDir = dirname(this.config.clientBundlePath);
         await mkdir(outputDir, { recursive: true });
         const inputFiles = await this.getInputFiles();
-        // Create a virtual entry that imports all files
-        const imports = inputFiles
+        // Discover serde files from the input files' dependency tree for cross-context class registration.
+        // Classes need to be registered in the client bundle so they can be serialized
+        // when passing data to workflows via start() and deserialized when receiving workflow results.
+        const { discoveredSerdeFiles } = await this.discoverEntries(inputFiles, outputDir);
+        // Identify serde files that aren't in the inputFiles (deduplicated)
+        const inputFilesNormalized = new Set(inputFiles.map((f) => f.replace(/\\/g, '/')));
+        const serdeOnlyFiles = discoveredSerdeFiles.filter((f) => !inputFilesNormalized.has(f));
+        // Re-exports for input files (user's workflow/step definitions)
+        const reexports = inputFiles
             .map((file) => `export * from '${file}';`)
             .join('\n');
+        // Side-effect imports for serde files not in inputFiles (for class registration)
+        const serdeImports = serdeOnlyFiles
+            .map((file) => {
+            const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');
+            let relativePath = relative(normalizedWorkingDir, file).replace(/\\/g, '/');
+            if (!relativePath.startsWith('.')) {
+                relativePath = `./${relativePath}`;
+            }
+            return `import '${relativePath}';`;
+        })
+            .join('\n');
+        // Combine: serde imports (for registration side effects) + re-exports
+        const entryContent = serdeImports
+            ? `// Serde files for cross-context class registration\n${serdeImports}\n${reexports}`
+            : reexports;
         // Bundle with esbuild and our custom SWC plugin
         const clientResult = await esbuild.build({
             banner: {
                 js: '// biome-ignore-all lint: generated file\n/* eslint-disable */\n',
             },
             stdin: {
-                contents: imports,
+                contents: entryContent,
                 resolveDir: this.config.workingDir,
                 sourcefile: 'virtual-entry.js',
                 loader: 'js',
@@ -453,11 +653,21 @@ export const POST = workflowEntrypoint(workflowCode);`;
             bundle: true,
             format: 'esm',
             platform: 'node',
+            jsx: 'preserve',
             target: 'es2022',
             write: true,
             treeShaking: true,
             external: ['@workflow/core'],
-            resolveExtensions: ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'],
+            resolveExtensions: [
+                '.ts',
+                '.tsx',
+                '.mts',
+                '.cts',
+                '.js',
+                '.jsx',
+                '.mjs',
+                '.cjs',
+            ],
             plugins: [createSwcPlugin({ mode: 'client' })],
         });
         this.logEsbuildMessages(clientResult, 'client library bundle');
@@ -470,7 +680,7 @@ export const POST = workflowEntrypoint(workflowCode);`;
      * @param bundle - If true, bundles dependencies (needed for Build Output API)
      */
     async createWebhookBundle({ outfile, bundle = false, }) {
-        console.log('Creating webhook route');
+        this.logCreateWebhookBundleInfo('Creating webhook route');
         await mkdir(dirname(outfile), { recursive: true });
         // Create a static route that calls resumeWebhook
         // This route works for both Next.js and Vercel Build Output API
@@ -512,7 +722,7 @@ export const OPTIONS = handler;`;
         const webhookBundleStart = Date.now();
         const result = await esbuild.build({
             banner: {
-                js: '// biome-ignore-all lint: generated file\n/* eslint-disable */\n',
+                js: `// biome-ignore-all lint: generated file\n/* eslint-disable */`,
             },
             stdin: {
                 contents: routeContent,
@@ -523,6 +733,7 @@ export const OPTIONS = handler;`;
             outfile,
             absWorkingDir: this.config.workingDir,
             bundle: true,
+            jsx: 'preserve',
             format: 'cjs',
             platform: 'node',
             conditions: ['import', 'module', 'node', 'default'],
@@ -531,14 +742,23 @@ export const OPTIONS = handler;`;
             treeShaking: true,
             keepNames: true,
             minify: false,
-            resolveExtensions: ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'],
-            sourcemap: false,
+            resolveExtensions: [
+                '.ts',
+                '.tsx',
+                '.mts',
+                '.cts',
+                '.js',
+                '.jsx',
+                '.mjs',
+                '.cjs',
+            ],
+            sourcemap: EMIT_SOURCEMAPS_FOR_DEBUGGING,
             mainFields: ['module', 'main'],
             // Don't externalize anything - bundle everything including workflow packages
             external: [],
         });
         this.logEsbuildMessages(result, 'webhook bundle creation');
-        console.log('Created webhook bundle', `${Date.now() - webhookBundleStart}ms`);
+        this.logCreateWebhookBundleInfo('Created webhook bundle', `${Date.now() - webhookBundleStart}ms`);
     }
     /**
      * Creates a package.json file with the specified module type.
@@ -586,5 +806,108 @@ export const OPTIONS = handler;`;
             // We're intentionally silently ignoring this error - creating .gitignore isn't critical
         }
     }
+    /**
+     * Whether the manifest should be exposed as a public HTTP route.
+     * Controlled by the `WORKFLOW_PUBLIC_MANIFEST` environment variable.
+     */
+    get shouldExposePublicManifest() {
+        return process.env.WORKFLOW_PUBLIC_MANIFEST === '1';
+    }
+    /**
+     * Whether diagnostics artifacts should be emitted to Vercel output.
+     * This is enabled when the resolved world target is Vercel.
+     */
+    get shouldEmitVercelDiagnostics() {
+        return (usesVercelWorld() || this.config.buildTarget === 'vercel-build-output-api');
+    }
+    /**
+     * Creates a manifest JSON file containing step/workflow/class metadata
+     * and graph data for visualization.
+     *
+     * @returns The manifest JSON string, or undefined if manifest creation failed.
+     */
+    async createManifest({ workflowBundlePath, manifestDir, manifest, }) {
+        const buildStart = Date.now();
+        this.logCreateManifestInfo('Creating manifest...');
+        try {
+            const workflowGraphs = await extractWorkflowGraphs(workflowBundlePath);
+            const steps = this.convertStepsManifest(manifest.steps);
+            const workflows = this.convertWorkflowsManifest(manifest.workflows, workflowGraphs);
+            const classes = this.convertClassesManifest(manifest.classes);
+            const output = { version: '1.0.0', steps, workflows, classes };
+            const manifestJson = JSON.stringify(output, null, 2);
+            await mkdir(manifestDir, { recursive: true });
+            await writeFile(join(manifestDir, 'manifest.json'), manifestJson);
+            if (this.shouldEmitVercelDiagnostics) {
+                const diagnosticsManifestPath = this.resolvePath('.vercel/output/diagnostics/workflows-manifest.json');
+                await this.ensureDirectory(diagnosticsManifestPath);
+                await writeFile(diagnosticsManifestPath, manifestJson);
+            }
+            const stepCount = Object.values(steps).reduce((acc, s) => acc + Object.keys(s).length, 0);
+            const workflowCount = Object.values(workflows).reduce((acc, w) => acc + Object.keys(w).length, 0);
+            const classCount = Object.values(classes).reduce((acc, c) => acc + Object.keys(c).length, 0);
+            this.logCreateManifestInfo(`Created manifest with ${stepCount} ${pluralize('step', 'steps', stepCount)}, ${workflowCount} ${pluralize('workflow', 'workflows', workflowCount)}, and ${classCount} ${pluralize('class', 'classes', classCount)}`, `${Date.now() - buildStart}ms`);
+            return manifestJson;
+        }
+        catch (error) {
+            console.warn('Failed to create manifest:', error instanceof Error ? error.message : String(error));
+            return undefined;
+        }
+    }
+    convertStepsManifest(steps) {
+        const result = {};
+        if (!steps)
+            return result;
+        for (const [filePath, entries] of Object.entries(steps)) {
+            result[filePath] = {};
+            for (const [name, data] of Object.entries(entries)) {
+                result[filePath][name] = { stepId: data.stepId };
+            }
+        }
+        return result;
+    }
+    convertWorkflowsManifest(workflows, graphs) {
+        const result = {};
+        if (!workflows)
+            return result;
+        // Build a normalized lookup for graphs since the graph extractor uses
+        // paths from workflowId (e.g. "./workflows/hello-agent") while the
+        // manifest uses source file paths (e.g. "workflows/hello-agent.ts").
+        // Normalize by stripping leading "./" and file extensions.
+        const normalizedGraphs = new Map();
+        for (const [graphPath, graphEntries] of Object.entries(graphs)) {
+            const normalized = graphPath
+                .replace(/^\.\//, '')
+                .replace(/\.[^/.]+$/, '');
+            normalizedGraphs.set(normalized, graphEntries);
+        }
+        for (const [filePath, entries] of Object.entries(workflows)) {
+            result[filePath] = {};
+            // Normalize the manifest file path for lookup
+            const normalizedFilePath = filePath
+                .replace(/^\.\//, '')
+                .replace(/\.[^/.]+$/, '');
+            const graphEntries = graphs[filePath] || normalizedGraphs.get(normalizedFilePath);
+            for (const [name, data] of Object.entries(entries)) {
+                result[filePath][name] = {
+                    workflowId: data.workflowId,
+                    graph: graphEntries?.[name]?.graph || { nodes: [], edges: [] },
+                };
+            }
+        }
+        return result;
+    }
+    convertClassesManifest(classes) {
+        const result = {};
+        if (!classes)
+            return result;
+        for (const [filePath, entries] of Object.entries(classes)) {
+            result[filePath] = {};
+            for (const [name, data] of Object.entries(entries)) {
+                result[filePath][name] = { classId: data.classId };
+            }
+        }
+        return result;
+    }
 }
 //# sourceMappingURL=base-builder.js.map