base-builder.ts

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 enhancedResolveOriginal from 'enhanced-resolve';
import * as esbuild from 'esbuild';
import { findUp } from 'find-up';
import { glob } from 'tinyglobby';
import {
  applySwcTransform,
  type WorkflowManifest,
} from './apply-swc-transform.js';
import { createDiscoverEntriesPlugin } from './discover-entries-esbuild-plugin.js';
import { getEsbuildTsconfigOptions } from './esbuild-tsconfig.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 type { WorkflowConfig } from './types.js';
import { extractWorkflowGraphs } from './workflows-extractor.js';

const enhancedResolve = promisify(enhancedResolveOriginal);

const EMIT_SOURCEMAPS_FOR_DEBUGGING =
  process.env.WORKFLOW_EMIT_SOURCEMAPS_FOR_DEBUGGING === '1';

/**
 * Normalize an array of file paths by appending the `realpath()` of each entry
 * (to handle symlinks, e.g. pnpm/workspace layouts) and deduplicating.
 */
async function withRealpaths(entries: string[]): Promise<string[]> {
  return Array.from(
    new Set(
      (
        await Promise.all(
          entries.map(async (entry) => {
            const resolved = await realpath(entry).catch(() => undefined);
            return resolved ? [entry, resolved] : [entry];
          })
        )
      ).flat()
    )
  );
}

export interface DiscoveredEntries {
  discoveredSteps: Set<string>;
  discoveredWorkflows: Set<string>;
  discoveredSerdeFiles: Set<string>;
}

/**
 * Base class for workflow builders. Provides common build logic for transforming
 * workflow source files into deployable bundles using esbuild and SWC.
 *
 * Subclasses must implement the build() method to define builder-specific logic.
 */
export abstract class BaseBuilder {
  protected config: WorkflowConfig;

  constructor(config: WorkflowConfig) {
    this.config = config;
  }

  protected get transformProjectRoot(): string {
    return this.config.projectRoot || this.config.workingDir;
  }

  /**
   * Whether informational BaseBuilder logs should be printed.
   * Subclasses can override this to silence progress logs while keeping warnings/errors.
   */
  protected get shouldLogBaseBuilderInfo(): boolean {
    return true;
  }

  protected logBaseBuilderInfo(...args: unknown[]): void {
    if (this.shouldLogBaseBuilderInfo) {
      console.log(...args);
    }
  }

  private logCreateWorkflowsBundleInfo(...args: unknown[]): void {
    if (!this.config.suppressCreateWorkflowsBundleLogs) {
      this.logBaseBuilderInfo(...args);
    }
  }

  private logCreateWebhookBundleInfo(...args: unknown[]): void {
    if (!this.config.suppressCreateWebhookBundleLogs) {
      this.logBaseBuilderInfo(...args);
    }
  }

  private logCreateManifestInfo(...args: unknown[]): void {
    if (!this.config.suppressCreateManifestLogs) {
      this.logBaseBuilderInfo(...args);
    }
  }

  /**
   * When outputting CJS, esbuild replaces `import.meta` with an empty object,
   * making `import.meta.url` (and `import.meta.resolve`) undefined. This method
   * returns banner code and `define` entries that polyfill them using CJS
   * equivalents (`__filename`, `require.resolve`) so user code (e.g. Prisma)
   * that relies on `import.meta.url` works correctly in bundled CJS output.
   */
  private getCjsImportMetaPolyfill(format: string): {
    banner: string;
    define: Record<string, string>;
  } {
    if (format !== 'cjs') return { banner: '', define: {} };
    return {
      banner:
        'var __import_meta_url = typeof __filename !== "undefined" ? require("url").pathToFileURL(__filename).href : undefined;\n' +
        'var __import_meta_resolve = typeof require !== "undefined" && typeof __filename !== "undefined" ' +
        '? (s) => require("url").pathToFileURL(require.resolve(s)).href : undefined;\n',
      define: {
        'import.meta.url': '__import_meta_url',
        'import.meta.resolve': '__import_meta_resolve',
      },
    };
  }

  /**
   * When outputting fully-bundled ESM, CJS dependencies that call require()
   * for Node.js builtins (e.g. debug → require('tty')) break because esbuild's
   * CJS-to-ESM __require shim doesn't have access to a real require function.
   * This banner provides one via createRequire so bundled CJS code works in ESM.
   */
  private getEsmRequireBanner(format: string): string {
    if (format !== 'esm') return '';
    return 'import { createRequire as __createRequire } from "node:module";\nvar require = __createRequire(import.meta.url);\n';
  }

  /**
   * Performs the complete build process for workflows.
   * Subclasses must implement this to define their specific build steps.
   */
  abstract build(): Promise<void>;

  /**
   * Finds tsconfig.json/jsconfig.json for the project.
   * Used by esbuild to properly resolve module imports during bundling.
   */
  protected async findTsConfigPath(): Promise<string | undefined> {
    const cwd = this.config.workingDir || process.cwd();
    return findUp(['tsconfig.json', 'jsconfig.json'], { cwd });
  }

  /**
   * Discovers all source files in the configured directories.
   * Searches for TypeScript and JavaScript files while excluding common build
   * and dependency directories.
   */
  protected async getInputFiles(): Promise<string[]> {
    const ignore = [
      '**/node_modules/**',
      '**/.git/**',
      '**/.next/**',
      '**/.nuxt/**',
      '**/.output/**',
      '**/.vercel/**',
      '**/.workflow-data/**',
      '**/.workflow-vitest/**',
      '**/.well-known/workflow/**',
      '**/.svelte-kit/**',
      '**/.turbo/**',
      '**/.cache/**',
      '**/.yarn/**',
      '**/.pnpm-store/**',
    ];

    // Use relative patterns with `cwd` per directory so that `dot: true`
    // applies consistently to both the search pattern *and* the ignore
    // patterns. When absolute patterns are used with tinyglobby, the `**`
    // in ignore patterns does not match dot-prefixed path segments.
    const results = await Promise.all(
      this.config.dirs.map((dir) => {
        const cwd = resolve(this.config.workingDir, dir);
        return glob(['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}'], {
          cwd,
          ignore,
          absolute: true,
          dot: true,
        });
      })
    );

    return results.flat();
  }

  /**
   * Caches discovered workflow entries by input array reference.
   * Uses WeakMap to allow garbage collection when input arrays are no longer referenced.
   * This cache is invalidated automatically when the inputs array reference changes
   * (e.g., when files are added/removed during watch mode).
   */
  private discoveredEntries: WeakMap<string[], DiscoveredEntries> =
    new WeakMap();

  protected async discoverEntries(
    inputs: string[],
    outdir: string,
    tsconfigPath?: string
  ): Promise<DiscoveredEntries> {
    const previousResult = this.discoveredEntries.get(inputs);

    if (previousResult) {
      return previousResult;
    }
    const state: DiscoveredEntries = {
      discoveredSteps: new Set(),
      discoveredWorkflows: new Set(),
      discoveredSerdeFiles: new Set(),
    };

    const discoverStart = Date.now();
    const effectiveTsconfigPath =
      tsconfigPath ?? (await this.findTsConfigPath());
    const esbuildTsconfigOptions = await getEsbuildTsconfigOptions(
      effectiveTsconfigPath
    );
    try {
      await esbuild.build({
        treeShaking: true,
        entryPoints: inputs,
        plugins: [
          createDiscoverEntriesPlugin(state, this.transformProjectRoot),
        ],
        platform: 'node',
        write: false,
        outdir,
        bundle: true,
        sourcemap: false,
        absWorkingDir: this.config.workingDir,
        logLevel: 'silent',
        ...esbuildTsconfigOptions,
        // External packages that should not be bundled during discovery
        external: this.config.externalPackages || [],
      });
    } catch (_) {}

    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.
   * Uses atomic write (temp file + rename) to prevent race conditions when
   * multiple builds run concurrently.
   */
  private async writeDebugFile(
    outfile: string,
    debugData: object,
    merge?: boolean
  ): Promise<void> {
    const prefix = this.config.debugFilePrefix || '';
    const targetPath = `${dirname(outfile)}/${prefix}${basename(outfile)}.debug.json`;
    let existing = {};

    try {
      if (merge) {
        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 as NodeJS.ErrnoException).code !== 'ENOENT') {
            console.warn('Error reading debug file, starting fresh:', e);
          }
        }
      }

      const mergedData = JSON.stringify(
        {
          ...existing,
          ...debugData,
        },
        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: unknown) {
      console.warn('Failed to write debug file:', error);
    }
  }

  /**
   * Logs and optionally throws on esbuild errors and warnings.
   * @param throwOnError - If true, throws an error when esbuild errors are present
   */
  private logEsbuildMessages(
    result: { errors?: any[]; warnings?: any[] },
    phase: string,
    throwOnError = true,
    options?: {
      suppressWarnings?: boolean;
    }
  ): void {
    if (result.errors && result.errors.length > 0) {
      console.error(`❌ esbuild errors in ${phase}:`);
      const errorMessages: string[] = [];
      for (const error of result.errors) {
        console.error(`  ${error.text}`);
        errorMessages.push(error.text);
        if (error.location) {
          const location = `    at ${error.location.file}:${error.location.line}:${error.location.column}`;
          console.error(location);
          errorMessages.push(location);
        }
      }

      if (throwOnError) {
        throw new Error(
          `Build failed during ${phase}:\n${errorMessages.join('\n')}`
        );
      }
    }

    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}`);
        if (warning.location) {
          console.warn(
            `    at ${warning.location.file}:${warning.location.line}:${warning.location.column}`
          );
        }
      }
    }
  }

  /**
   * Converts an absolute file path to a normalized relative path for the manifest.
   */
  private getRelativeFilepath(absolutePath: string): string {
    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
   */
  protected async createStepsBundle({
    inputFiles,
    format = 'esm',
    outfile,
    externalizeNonSteps,
    rewriteTsExtensions,
    tsconfigPath,
    discoveredEntries,
  }: {
    tsconfigPath?: string;
    inputFiles: string[];
    outfile: string;
    format?: 'cjs' | 'esm';
    externalizeNonSteps?: boolean;
    rewriteTsExtensions?: boolean;
    discoveredEntries?: DiscoveredEntries;
  }): Promise<{
    context: esbuild.BuildContext | undefined;
    manifest: WorkflowManifest;
  }> {
    // These need to handle watching for dev to scan for
    // new entries and changes to existing ones
    const discovered =
      discoveredEntries ??
      (await this.discoverEntries(inputFiles, dirname(outfile), tsconfigPath));
    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,
      workflowFiles,
      serdeOnlyFiles,
    });

    const stepsBundleStart = Date.now();
    const workflowManifest: WorkflowManifest = {};
    const builtInSteps = 'workflow/internal/builtins';

    const resolvedBuiltInSteps = await enhancedResolve(
      dirname(outfile),
      'workflow/internal/builtins'
    ).catch((err) => {
      throw new Error(
        [
          chalk.red('Failed to resolve built-in steps sources.'),
          `${chalk.yellow.bold('hint:')} run \`${chalk.cyan.italic('npm install workflow')}\` to resolve this issue.`,
          '',
          `Caused by: ${chalk.red(String(err))}`,
        ].join('\n')
      );
    });

    // 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: string) => {
      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, '/');
      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.
      // Paths like ".output/..." are not valid relative specifiers and must
      // become "./.output/...".
      if (!relativePath.startsWith('./') && !relativePath.startsWith('../')) {
        relativePath = `./${relativePath}`;
      }
      return `import '${relativePath}';`;
    };

    // 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
    ${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
      ? await withRealpaths(entriesToBundle)
      : undefined;
    const normalizedSideEffectEntries = await withRealpaths([
      ...stepFiles,
      ...serdeOnlyFiles,
      ...(resolvedBuiltInSteps ? [resolvedBuiltInSteps] : []),
    ]);
    const esbuildTsconfigOptions =
      await getEsbuildTsconfigOptions(tsconfigPath);
    const { banner: importMetaBanner, define: importMetaDefine } =
      this.getCjsImportMetaPolyfill(format);
    const esmRequireBanner = this.getEsmRequireBanner(format);

    const esbuildCtx = await esbuild.context({
      banner: {
        js: `// biome-ignore-all lint: generated file\n/* eslint-disable */\n${importMetaBanner}${esmRequireBanner}`,
      },
      stdin: {
        contents: entryContent,
        resolveDir: this.config.workingDir,
        sourcefile: 'virtual-entry.js',
        loader: 'js',
      },
      outfile,
      absWorkingDir: this.config.workingDir,
      bundle: true,
      format,
      platform: 'node',
      conditions: ['node'],
      target: 'es2022',
      write: true,
      treeShaking: true,
      keepNames: true,
      minify: false,
      jsx: 'preserve',
      logLevel: 'error',
      // Use tsconfig for path alias resolution.
      // For symlinked configs this uses tsconfigRaw to preserve cwd-relative aliases.
      ...esbuildTsconfigOptions,
      define: importMetaDefine,
      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: normalizedEntriesToBundle,
          outdir: outfile ? dirname(outfile) : undefined,
          projectRoot: this.transformProjectRoot,
          workflowManifest,
          rewriteTsExtensions,
          sideEffectEntries: normalizedSideEffectEntries,
        }),
      ],
      // Plugin should catch most things, but this lets users hard override
      // if the plugin misses anything that should be externalized
      external: ['bun', 'bun:*', ...(this.config.externalPackages || [])],
    });

    const stepsResult = await esbuildCtx.rebuild();

    this.logEsbuildMessages(stepsResult, 'steps bundle creation');
    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',
            workflowFile,
            this.transformProjectRoot
          );
          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 { context: esbuildCtx, manifest: workflowManifest };
    }
    await esbuildCtx.dispose();
    return { context: undefined, manifest: workflowManifest };
  }

  /**
   * Creates a bundle for workflow orchestration functions.
   * Workflows run in a sandboxed VM and coordinate step execution.
   *
   * @param bundleFinalOutput - If false, skips the final bundling step (used by Next.js)
   */
  protected async createWorkflowsBundle({
    inputFiles,
    format = 'esm',
    outfile,
    bundleFinalOutput = true,
    keepInterimBundleContext = this.config.watch,
    tsconfigPath,
    discoveredEntries,
  }: {
    tsconfigPath?: string;
    inputFiles: string[];
    outfile: string;
    format?: 'cjs' | 'esm';
    bundleFinalOutput?: boolean;
    keepInterimBundleContext?: boolean;
    discoveredEntries?: DiscoveredEntries;
  }): Promise<{
    manifest: WorkflowManifest;
    interimBundleCtx?: esbuild.BuildContext;
    bundleFinal?: (interimBundleResult: string) => Promise<void>;
  }> {
    const discovered =
      discoveredEntries ??
      (await this.discoverEntries(inputFiles, dirname(outfile), tsconfigPath));
    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, 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: string) => {
      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.
      // Paths like ".output/..." are not valid relative specifiers and must
      // become "./.output/...".
      if (!relativePath.startsWith('./') && !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: WorkflowManifest = {};
    const esbuildTsconfigOptions =
      await getEsbuildTsconfigOptions(tsconfigPath);
    const normalizedWorkflowSideEffectEntries = await withRealpaths([
      ...workflowFiles,
      ...serdeOnlyFiles,
    ]);

    // Bundle with esbuild and our custom SWC plugin in workflow mode.
    // this bundle will be run inside a vm isolate
    const interimBundleCtx = await esbuild.context({
      stdin: {
        contents: imports,
        resolveDir: this.config.workingDir,
        sourcefile: 'virtual-entry.js',
        loader: 'js',
      },
      bundle: true,
      absWorkingDir: this.config.workingDir,
      format: 'cjs', // Runs inside the VM which expects cjs
      platform: 'neutral', // The platform is neither node nor browser
      mainFields: ['module', 'main'], // To support npm style imports
      conditions: ['workflow'], // Allow packages to export 'workflow' compliant versions
      target: 'es2022',
      write: false,
      treeShaking: true,
      keepNames: true,
      minify: false,
      // 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.
      // For symlinked configs this uses tsconfigRaw to preserve cwd-relative aliases.
      ...esbuildTsconfigOptions,
      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',
          projectRoot: this.transformProjectRoot,
          workflowManifest,
          sideEffectEntries: normalizedWorkflowSideEffectEntries,
        }),
        // 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
    });
    let shouldDisposeInterimBundleCtx = !keepInterimBundleContext;
    try {
      const interimBundle = await interimBundleCtx.rebuild();

      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 = '';

        if (resolvedPath.endsWith('.cjs')) {
          prefix = 'module.exports = ';
        } else if (
          resolvedPath.endsWith('.js') ||
          resolvedPath.endsWith('.mjs')
        ) {
          prefix = 'export default ';
        }

        await mkdir(dirname(resolvedPath), { recursive: true });
        await writeFile(
          resolvedPath,
          prefix + JSON.stringify(workflowManifest, null, 2)
        );
      }

      // Create .gitignore in .swc directory
      await this.createSwcGitignore();

      if (
        !interimBundle.outputFiles ||
        interimBundle.outputFiles.length === 0
      ) {
        throw new Error('No output files generated from esbuild');
      }

      // Serde compliance warnings: check if workflow bundle has Node.js imports
      // alongside serde-registered classes (these will fail at runtime in the sandbox)
      if (
        workflowManifest.classes &&
        Object.keys(workflowManifest.classes).length > 0
      ) {
        const { analyzeSerdeCompliance } = await import('./serde-checker.js');
        const bundleText = interimBundle.outputFiles[0].text;
        const serdeResult = analyzeSerdeCompliance({
          sourceCode: '',
          workflowCode: bundleText,
          manifest: workflowManifest,
        });
        // De-dupe warnings: group identical issues across classes
        const issuesToClasses = new Map<string, Set<string>>();
        for (const cls of serdeResult.classes) {
          if (!cls.compliant) {
            for (const issue of cls.issues) {
              let affectedClasses = issuesToClasses.get(issue);
              if (!affectedClasses) {
                affectedClasses = new Set<string>();
                issuesToClasses.set(issue, affectedClasses);
              }
              affectedClasses.add(cls.className);
            }
          }
        }
        for (const [issue, affectedClasses] of issuesToClasses) {
          const classNames = [...affectedClasses];
          const classLabel =
            classNames.length === 1
              ? `class "${classNames[0]}"`
              : `classes ${classNames.map((name) => `"${name}"`).join(', ')}`;
          console.warn(
            chalk.yellow(`⚠ Serde warning for ${classLabel}: `) + issue
          );
        }
      }

      const bundleFinal = async (interimBundle: string) => {
        const workflowBundleCode = interimBundle;

        const workflowFunctionCode = `// biome-ignore-all lint: generated file
/* eslint-disable */
import { workflowEntrypoint } from 'workflow/runtime';

const workflowCode = \`${workflowBundleCode.replace(/[\\`$]/g, '\\$&')}\`;

export const POST = workflowEntrypoint(workflowCode);`;

        // we skip the final bundling step for Next.js so it can bundle itself
        if (!bundleFinalOutput) {
          if (!outfile) {
            throw new Error(`Invariant: missing outfile for workflow bundle`);
          }
          // Ensure the output directory exists
          const outputDir = dirname(outfile);
          await mkdir(outputDir, { recursive: true });

          // 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();

        // Now bundle this so we can resolve the @workflow/core dependency
        // we could remove this if we do nft tracing or similar instead
        const finalEsmRequireBanner = this.getEsmRequireBanner(format);
        const finalWorkflowResult = await esbuild.build({
          banner: {
            js: `// biome-ignore-all lint: generated file\n/* eslint-disable */\n${finalEsmRequireBanner}`,
          },
          stdin: {
            contents: workflowFunctionCode,
            resolveDir: this.config.workingDir,
            sourcefile: 'virtual-entry.js',
            loader: 'js',
          },
          outfile,
          // 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,
          format,
          platform: 'node',
          target: 'es2022',
          write: true,
          keepNames: true,
          minify: false,
          external: ['@aws-sdk/credential-provider-web-identity'],
        });

        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 (keepInterimBundleContext) {
        shouldDisposeInterimBundleCtx = false;
        return {
          manifest: workflowManifest,
          interimBundleCtx,
          bundleFinal,
        };
      }
      return { manifest: workflowManifest };
    } catch (error) {
      shouldDisposeInterimBundleCtx = true;
      throw error;
    } finally {
      if (shouldDisposeInterimBundleCtx) {
        try {
          await interimBundleCtx.dispose();
        } catch (disposeError) {
          console.warn(
            'Warning: Failed to dispose workflow bundle context',
            disposeError
          );
        }
      }
    }
  }

  /**
   * Creates a client library bundle for workflow execution.
   * The client library allows importing and calling workflows from application code.
   * Only generated if clientBundlePath is specified in config.
   */
  protected async createClientLibrary(): Promise<void> {
    if (!this.config.clientBundlePath) {
      // Silently exit since no client bundle was requested
      return;
    }

    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();

    // 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).
    // These must use valid relative specifiers because some frameworks pass
    // generated files like ".output/server/index.mjs" as input files.
    const reexports = inputFiles
      .map((file) => {
        const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');
        let relativePath = relative(normalizedWorkingDir, file).replace(
          /\\/g,
          '/'
        );
        if (!relativePath.startsWith('./') && !relativePath.startsWith('../')) {
          relativePath = `./${relativePath}`;
        }
        return `export * from '${relativePath}';`;
      })
      .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.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 normalizedClientSideEffectEntries = await withRealpaths([
      ...inputFiles,
      ...serdeOnlyFiles,
    ]);
    const clientResult = await esbuild.build({
      banner: {
        js: '// biome-ignore-all lint: generated file\n/* eslint-disable */\n',
      },
      stdin: {
        contents: entryContent,
        resolveDir: this.config.workingDir,
        sourcefile: 'virtual-entry.js',
        loader: 'js',
      },
      outfile: this.config.clientBundlePath,
      bundle: true,
      format: 'esm',
      platform: 'node',
      jsx: 'preserve',
      target: 'es2022',
      write: true,
      treeShaking: true,
      external: ['@workflow/core'],
      resolveExtensions: [
        '.ts',
        '.tsx',
        '.mts',
        '.cts',
        '.js',
        '.jsx',
        '.mjs',
        '.cjs',
      ],
      plugins: [
        createSwcPlugin({
          mode: 'client',
          projectRoot: this.transformProjectRoot,
          sideEffectEntries: normalizedClientSideEffectEntries,
        }),
      ],
    });

    this.logEsbuildMessages(clientResult, 'client library bundle');

    // Create .gitignore in .swc directory
    await this.createSwcGitignore();
  }

  /**
   * Creates a webhook handler bundle for resuming workflows via HTTP callbacks.
   *
   * @param bundle - If true, bundles dependencies (needed for Build Output API)
   */
  protected async createWebhookBundle({
    outfile,
    bundle = false,
  }: {
    outfile: string;
    bundle?: boolean;
  }): Promise<void> {
    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
    const routeContent = `import { resumeWebhook } from 'workflow/api';

async function handler(request) {
  const url = new URL(request.url);
  // Extract token from pathname: /.well-known/workflow/v1/webhook/{token}
  const pathParts = url.pathname.split('/');
  const token = decodeURIComponent(pathParts[pathParts.length - 1]);

  if (!token) {
    return new Response('Missing token', { status: 400 });
  }

  try {
    const response = await resumeWebhook(token, request);
    return response;
  } catch (error) {
    // TODO: differentiate between invalid token and other errors
    console.error('Error during resumeWebhook', error);
    return new Response(null, { status: 404 });
  }
}

export const GET = handler;
export const POST = handler;
export const PUT = handler;
export const PATCH = handler;
export const DELETE = handler;
export const HEAD = handler;
export const OPTIONS = handler;`;

    if (!bundle) {
      // For Next.js, just write the unbundled file
      await writeFile(outfile, routeContent);
      return;
    }

    // For Build Output API, bundle with esbuild to resolve imports

    const webhookEsmRequireBanner = this.getEsmRequireBanner('esm');
    const webhookBundleStart = Date.now();
    const result = await esbuild.build({
      banner: {
        js: `// biome-ignore-all lint: generated file\n/* eslint-disable */\n${webhookEsmRequireBanner}`,
      },
      stdin: {
        contents: routeContent,
        resolveDir: this.config.workingDir,
        sourcefile: 'webhook-route.js',
        loader: 'js',
      },
      outfile,
      absWorkingDir: this.config.workingDir,
      bundle: true,
      jsx: 'preserve',
      format: 'esm',
      platform: 'node',
      conditions: ['import', 'module', 'node', 'default'],
      target: 'es2022',
      write: true,
      treeShaking: true,
      keepNames: true,
      minify: 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');
    this.logCreateWebhookBundleInfo(
      'Created webhook bundle',
      `${Date.now() - webhookBundleStart}ms`
    );
  }

  /**
   * Creates a package.json file with the specified module type.
   */
  protected async createPackageJson(
    dir: string,
    type: 'commonjs' | 'module'
  ): Promise<void> {
    const packageJson = { type };
    await writeFile(
      join(dir, 'package.json'),
      JSON.stringify(packageJson, null, 2)
    );
  }

  /**
   * Creates a .vc-config.json file for Vercel Build Output API functions.
   */
  protected async createVcConfig(
    dir: string,
    config: {
      runtime?: string;
      handler?: string;
      launcherType?: string;
      architecture?: string;
      shouldAddHelpers?: boolean;
      shouldAddSourcemapSupport?: boolean;
      maxDuration?: number | 'max';
      experimentalTriggers?: Array<{
        type: 'queue/v2beta';
        topic: string;
        consumer: string;
        maxDeliveries?: number;
        retryAfterSeconds?: number;
        initialDelaySeconds?: number;
      }>;
    }
  ): Promise<void> {
    const vcConfig = {
      runtime: config.runtime ?? 'nodejs22.x',
      handler: config.handler ?? 'index.mjs',
      launcherType: config.launcherType ?? 'Nodejs',
      architecture: config.architecture ?? 'arm64',
      shouldAddHelpers: config.shouldAddHelpers ?? true,
      ...(config.maxDuration !== undefined && {
        maxDuration: config.maxDuration,
      }),
      ...(config.shouldAddSourcemapSupport !== undefined && {
        shouldAddSourcemapSupport: config.shouldAddSourcemapSupport,
      }),
      ...(config.experimentalTriggers && {
        experimentalTriggers: config.experimentalTriggers,
      }),
    };

    await writeFile(
      join(dir, '.vc-config.json'),
      JSON.stringify(vcConfig, null, 2)
    );
  }

  /**
   * Resolves a path relative to the working directory.
   */
  protected resolvePath(path: string): string {
    return resolve(this.config.workingDir, path);
  }

  /**
   * Ensures the directory for a file path exists, creating it if necessary.
   */
  protected async ensureDirectory(filePath: string): Promise<void> {
    await mkdir(dirname(filePath), { recursive: true });
  }

  private async createSwcGitignore(): Promise<void> {
    try {
      await writeFile(
        join(this.config.workingDir, '.swc', '.gitignore'),
        '*\n'
      );
    } catch {
      // 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.
   */
  protected get shouldExposePublicManifest(): boolean {
    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.
   */
  protected get shouldEmitVercelDiagnostics(): boolean {
    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.
   */
  protected async createManifest({
    workflowBundlePath,
    manifestDir,
    manifest,
  }: {
    workflowBundlePath: string;
    manifestDir: string;
    manifest: WorkflowManifest;
  }): Promise<string | undefined> {
    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;
    }
  }

  private convertStepsManifest(
    steps: WorkflowManifest['steps']
  ): Record<string, Record<string, { stepId: string }>> {
    const result: Record<string, Record<string, { stepId: string }>> = {};
    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;
  }

  private convertWorkflowsManifest(
    workflows: WorkflowManifest['workflows'],
    graphs: Record<
      string,
      Record<string, { graph: { nodes: any[]; edges: any[] } }>
    >
  ): Record<
    string,
    Record<
      string,
      { workflowId: string; graph: { nodes: any[]; edges: any[] } }
    >
  > {
    const result: Record<
      string,
      Record<
        string,
        { workflowId: string; graph: { nodes: any[]; edges: any[] } }
      >
    > = {};
    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<
      string,
      Record<string, { graph: { nodes: any[]; edges: any[] } }>
    >();
    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;
  }

  private convertClassesManifest(
    classes: WorkflowManifest['classes']
  ): Record<string, Record<string, { classId: string }>> {
    const result: Record<string, Record<string, { classId: string }>> = {};
    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;
  }
}