@workflow/builders 4.0.4 → 4.0.6

package/dist/base-builder.d.ts

@@ -1,10 +1,11 @@
 import * as esbuild from 'esbuild';
 import { type WorkflowManifest } from './apply-swc-transform.js';
 import type { WorkflowConfig } from './types.js';
+export type DiscoveredEntryCollection = string[] | Set<string>;
 export interface DiscoveredEntries {
-    discoveredSteps: string[];
-    discoveredWorkflows: string[];
-    discoveredSerdeFiles: string[];
+    discoveredSteps: DiscoveredEntryCollection;
+    discoveredWorkflows: DiscoveredEntryCollection;
+    discoveredSerdeFiles: DiscoveredEntryCollection;
 }
 /**
  * Base class for workflow builders. Provides common build logic for transforming
@@ -14,6 +15,11 @@ export interface DiscoveredEntries {
  */
 export declare abstract class BaseBuilder {
     protected config: WorkflowConfig;
+    /**
+     * Tracks which external packages have already been warned about
+     * to avoid duplicate warnings across multiple discoverEntries() calls.
+     */
+    private warnedExternalPackages;
     constructor(config: WorkflowConfig);
     protected get transformProjectRoot(): string;
     /**
@@ -56,6 +62,17 @@ export declare abstract class BaseBuilder {
      * (e.g., when files are added/removed during watch mode).
      */
     private discoveredEntries;
+    /**
+     * Pseudo-packages that should not be checked for workflow patterns.
+     */
+    private static readonly PSEUDO_PACKAGES;
+    /**
+     * Checks each package in externalPackages for workflow patterns and emits
+     * warnings if any contain "use step", "use workflow" directives, or
+     * serialization classes. These patterns will not be transformed by the
+     * workflow compiler when the package is externalized.
+     */
+    private warnAboutExternalWorkflowPackages;
     protected discoverEntries(inputs: string[], outdir: string, tsconfigPath?: string): Promise<DiscoveredEntries>;
     /**
      * Writes debug information to a JSON file for troubleshooting build issues.
@@ -77,14 +94,16 @@ export declare abstract class BaseBuilder {
      * 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
+     * @param bundleTransitiveLocalStepDependencies - If true, also bundles project-local files imported by step entries for direct runtime loading
      * @returns Build context (for watch mode) and the collected workflow manifest
      */
-    protected createStepsBundle({ inputFiles, format, outfile, externalizeNonSteps, rewriteTsExtensions, tsconfigPath, discoveredEntries, }: {
+    protected createStepsBundle({ inputFiles, format, outfile, externalizeNonSteps, bundleTransitiveLocalStepDependencies, rewriteTsExtensions, tsconfigPath, discoveredEntries, }: {
         tsconfigPath?: string;
         inputFiles: string[];
         outfile: string;
         format?: 'cjs' | 'esm';
         externalizeNonSteps?: boolean;
+        bundleTransitiveLocalStepDependencies?: boolean;
         rewriteTsExtensions?: boolean;
         discoveredEntries?: DiscoveredEntries;
     }): Promise<{

package/dist/base-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-builder.d.ts","sourceRoot":"","sources":["../src/base-builder.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AAGnC,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,0BAA0B,CAAC;AAOlC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA2BjD,MAAM,WAAW,iBAAiB;IAChC,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC;AAED;;;;;GAKG;AACH,8BAAsB,WAAW;IAC/B,SAAS,CAAC,MAAM,EAAE,cAAc,CAAC;gBAErB,MAAM,EAAE,cAAc;IAIlC,SAAS,KAAK,oBAAoB,IAAI,MAAM,CAE3C;IAED;;;OAGG;IACH,SAAS,KAAK,wBAAwB,IAAI,OAAO,CAEhD;IAED,SAAS,CAAC,kBAAkB,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAMtD,OAAO,CAAC,4BAA4B;IAMpC,OAAO,CAAC,0BAA0B;IAMlC,OAAO,CAAC,qBAAqB;IAM7B;;;;;;OAMG;IACH,OAAO,CAAC,wBAAwB;IAiBhC;;;OAGG;IACH,QAAQ,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAE/B;;;OAGG;cACa,gBAAgB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAK/D;;;;OAIG;cACa,aAAa,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAqClD;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB,CAOP;cAEF,eAAe,CAC7B,MAAM,EAAE,MAAM,EAAE,EAChB,MAAM,EAAE,MAAM,EACd,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,iBAAiB,CAAC;IAmD7B;;;;OAIG;YACW,cAAc;IA2C5B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IA6C1B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAiB3B;;;;;;OAMG;cACa,iBAAiB,CAAC,EAChC,UAAU,EACV,MAAc,EACd,OAAO,EACP,mBAAmB,EACnB,mBAAmB,EACnB,YAAY,EACZ,iBAAiB,GAClB,EAAE;QACD,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,MAAM,EAAE,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;QACvB,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAC9B,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAC9B,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;KACvC,GAAG,OAAO,CAAC;QACV,OAAO,EAAE,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;QAC1C,QAAQ,EAAE,gBAAgB,CAAC;KAC5B,CAAC;IAuOF;;;;;OAKG;cACa,qBAAqB,CAAC,EACpC,UAAU,EACV,MAAc,EACd,OAAO,EACP,iBAAwB,EACxB,wBAA4C,EAC5C,YAAY,EACZ,iBAAiB,GAClB,EAAE;QACD,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,MAAM,EAAE,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;QACvB,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,wBAAwB,CAAC,EAAE,OAAO,CAAC;QACnC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;KACvC,GAAG,OAAO,CAAC;QACV,QAAQ,EAAE,gBAAgB,CAAC;QAC3B,gBAAgB,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC;QACxC,WAAW,CAAC,EAAE,CAAC,mBAAmB,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KAC9D,CAAC;IAoUF;;;;OAIG;cACa,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IA0HpD;;;;OAIG;cACa,mBAAmB,CAAC,EAClC,OAAO,EACP,MAAc,GACf,EAAE;QACD,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,GAAG,OAAO,CAAC,IAAI,CAAC;IA+FjB;;OAEG;cACa,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,UAAU,GAAG,QAAQ,GAC1B,OAAO,CAAC,IAAI,CAAC;IAQhB;;OAEG;cACa,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE;QACN,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,yBAAyB,CAAC,EAAE,OAAO,CAAC;QACpC,WAAW,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;QAC7B,oBAAoB,CAAC,EAAE,KAAK,CAAC;YAC3B,IAAI,EAAE,cAAc,CAAC;YACrB,KAAK,EAAE,MAAM,CAAC;YACd,QAAQ,EAAE,MAAM,CAAC;YACjB,aAAa,CAAC,EAAE,MAAM,CAAC;YACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;YAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAC;SAC9B,CAAC,CAAC;KACJ,GACA,OAAO,CAAC,IAAI,CAAC;IAwBhB;;OAEG;IACH,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI3C;;OAEG;cACa,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAIlD,kBAAkB;IAWhC;;;OAGG;IACH,SAAS,KAAK,0BAA0B,IAAI,OAAO,CAElD;IAED;;;OAGG;IACH,SAAS,KAAK,2BAA2B,IAAI,OAAO,CAInD;IAED;;;;;OAKG;cACa,cAAc,CAAC,EAC7B,kBAAkB,EAClB,WAAW,EACX,QAAQ,GACT,EAAE;QACD,kBAAkB,EAAE,MAAM,CAAC;QAC3B,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,gBAAgB,CAAC;KAC5B,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAuD/B,OAAO,CAAC,oBAAoB;IAe5B,OAAO,CAAC,wBAAwB;IAyDhC,OAAO,CAAC,sBAAsB;CAc/B"}
+{"version":3,"file":"base-builder.d.ts","sourceRoot":"","sources":["../src/base-builder.ts"],"names":[],"mappings":"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"}

package/dist/base-builder.js

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { mkdir, readFile, realpath, rename, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { promisify } from 'node:util';
 import { pluralize, usesVercelWorld } from '@workflow/utils';
@@ -15,8 +16,10 @@ 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 { detectWorkflowPatterns } from './transform-utils.js';
 import { extractWorkflowGraphs } from './workflows-extractor.js';
 const enhancedResolve = promisify(enhancedResolveOriginal);
+const require = createRequire(import.meta.url);
 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
@@ -36,6 +39,11 @@ async function withRealpaths(entries) {
  */
 export class BaseBuilder {
     config;
+    /**
+     * Tracks which external packages have already been warned about
+     * to avoid duplicate warnings across multiple discoverEntries() calls.
+     */
+    warnedExternalPackages = new Set();
     constructor(config) {
         this.config = config;
     }
@@ -141,15 +149,114 @@ export class BaseBuilder {
      * (e.g., when files are added/removed during watch mode).
      */
     discoveredEntries = new WeakMap();
+    /**
+     * Pseudo-packages that should not be checked for workflow patterns.
+     */
+    static PSEUDO_PACKAGES = new Set([
+        'server-only',
+        'client-only',
+    ]);
+    /**
+     * Checks each package in externalPackages for workflow patterns and emits
+     * warnings if any contain "use step", "use workflow" directives, or
+     * serialization classes. These patterns will not be transformed by the
+     * workflow compiler when the package is externalized.
+     */
+    async warnAboutExternalWorkflowPackages() {
+        const externalPackages = this.config.externalPackages;
+        if (!externalPackages?.length)
+            return;
+        for (const pkg of externalPackages) {
+            if (BaseBuilder.PSEUDO_PACKAGES.has(pkg))
+                continue;
+            if (this.warnedExternalPackages.has(pkg))
+                continue;
+            if (pkg.startsWith('.') ||
+                pkg.startsWith('/') ||
+                pkg.startsWith('$') ||
+                pkg.includes('*') ||
+                pkg.includes(':')) {
+                continue;
+            }
+            try {
+                // Check package.json dependencies for @workflow/serde (fast path)
+                let hasWorkflowSerdeDep = false;
+                try {
+                    const pkgJsonPath = require.resolve(`${pkg}/package.json`, {
+                        paths: [this.config.workingDir],
+                    });
+                    const pkgJsonSource = await readFile(pkgJsonPath, 'utf-8');
+                    const pkgJson = JSON.parse(pkgJsonSource);
+                    const dependencies = typeof pkgJson.dependencies === 'object' &&
+                        pkgJson.dependencies !== null &&
+                        !Array.isArray(pkgJson.dependencies)
+                        ? pkgJson.dependencies
+                        : {};
+                    const peerDependencies = typeof pkgJson.peerDependencies === 'object' &&
+                        pkgJson.peerDependencies !== null &&
+                        !Array.isArray(pkgJson.peerDependencies)
+                        ? pkgJson.peerDependencies
+                        : {};
+                    hasWorkflowSerdeDep =
+                        Object.hasOwn(dependencies, '@workflow/serde') ||
+                            Object.hasOwn(peerDependencies, '@workflow/serde');
+                }
+                catch {
+                    // package.json not resolvable - continue to source check
+                }
+                // Check source patterns (thorough path).
+                // Note: require.resolve only inspects the package's main entry point.
+                // If workflow constructs live in sub-paths (e.g. `my-pkg/workflows`),
+                // they won't be detected here. The @workflow/serde dep check above
+                // partially covers serde cases. This is acceptable as a best-effort
+                // heuristic — the primary fix is auto-removal in withWorkflow().
+                let hasUseStep = false;
+                let hasUseWorkflow = false;
+                let hasSerde = hasWorkflowSerdeDep;
+                try {
+                    const entryPath = require.resolve(pkg, {
+                        paths: [this.config.workingDir],
+                    });
+                    const source = await readFile(entryPath, 'utf-8');
+                    const patterns = detectWorkflowPatterns(source);
+                    hasUseStep = patterns.hasUseStep;
+                    hasUseWorkflow = patterns.hasUseWorkflow;
+                    if (!hasSerde) {
+                        hasSerde = patterns.hasSerde;
+                    }
+                }
+                catch {
+                    // Entry file not resolvable or not readable - use what we have
+                }
+                if (!hasUseStep && !hasUseWorkflow && !hasSerde)
+                    continue;
+                // Build a specific description of what was found
+                const issues = [];
+                if (hasUseWorkflow)
+                    issues.push('"use workflow" functions');
+                if (hasUseStep)
+                    issues.push('"use step" functions');
+                if (hasSerde)
+                    issues.push('serialization classes');
+                this.warnedExternalPackages.add(pkg);
+                console.warn(`\n${chalk.yellow('⚠')} Warning: ${chalk.bold(`"${pkg}"`)} is listed in ${chalk.bold('externalPackages')} (${chalk.bold('serverExternalPackages')} in Next.js) but contains workflow code (${issues.join(', ')}).` +
+                    `\n  This code will ${chalk.bold('not')} be transformed by the workflow compiler, which can cause runtime failures.` +
+                    `\n  Remove ${chalk.bold(`"${pkg}"`)} from ${chalk.bold('externalPackages')} (${chalk.bold('serverExternalPackages')} in Next.js) to fix this.\n`);
+            }
+            catch {
+                // Best-effort: if anything goes wrong, skip this package silently
+            }
+        }
+    }
     async discoverEntries(inputs, outdir, tsconfigPath) {
         const previousResult = this.discoveredEntries.get(inputs);
         if (previousResult) {
             return previousResult;
         }
         const state = {
-            discoveredSteps: [],
-            discoveredWorkflows: [],
-            discoveredSerdeFiles: [],
+            discoveredSteps: new Set(),
+            discoveredWorkflows: new Set(),
+            discoveredSerdeFiles: new Set(),
         };
         const discoverStart = Date.now();
         const effectiveTsconfigPath = tsconfigPath ?? (await this.findTsConfigPath());
@@ -175,6 +282,8 @@ export class BaseBuilder {
         }
         catch (_) { }
         this.logBaseBuilderInfo(`Discovering workflow directives`, `${Date.now() - discoverStart}ms`);
+        // Warn about external packages that contain workflow code
+        await this.warnAboutExternalWorkflowPackages();
         this.discoveredEntries.set(inputs, state);
         return state;
     }
@@ -270,9 +379,10 @@ export class BaseBuilder {
      * 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
+     * @param bundleTransitiveLocalStepDependencies - If true, also bundles project-local files imported by step entries for direct runtime loading
      * @returns Build context (for watch mode) and the collected workflow manifest
      */
-    async createStepsBundle({ inputFiles, format = 'cjs', outfile, externalizeNonSteps, rewriteTsExtensions, tsconfigPath, discoveredEntries, }) {
+    async createStepsBundle({ inputFiles, format = 'cjs', outfile, externalizeNonSteps, bundleTransitiveLocalStepDependencies, rewriteTsExtensions, tsconfigPath, discoveredEntries, }) {
         // These need to handle watching for dev to scan for
         // new entries and changes to existing ones
         const discovered = discoveredEntries ??
@@ -339,7 +449,7 @@ export class BaseBuilder {
     // Serde files for cross-context class registration
     ${serdeImports}
     // API entrypoint
-    export { stepEntrypoint as POST } from 'workflow/runtime';`;
+    export { stepEntrypoint as HEAD, stepEntrypoint as POST } from 'workflow/runtime';`;
         // Bundle with esbuild and our custom SWC plugin
         const entriesToBundle = externalizeNonSteps
             ? [
@@ -410,6 +520,7 @@ export class BaseBuilder {
                     outdir: outfile ? dirname(outfile) : undefined,
                     projectRoot: this.transformProjectRoot,
                     workflowManifest,
+                    bundleTransitiveLocalStepDependencies,
                     rewriteTsExtensions,
                     sideEffectEntries: normalizedSideEffectEntries,
                 }),
@@ -642,7 +753,10 @@ import { workflowEntrypoint } from 'workflow/runtime';
 
 const workflowCode = \`${workflowBundleCode.replace(/[\\`$]/g, '\\$&')}\`;
 
-export const POST = workflowEntrypoint(workflowCode);`;
+const handler = workflowEntrypoint(workflowCode);
+
+export const HEAD = handler;
+export const POST = handler;`;
                 // we skip the final bundling step for Next.js so it can bundle itself
                 if (!bundleFinalOutput) {
                     if (!outfile) {
@@ -738,7 +852,7 @@ export const POST = workflowEntrypoint(workflowCode);`;
         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));
+        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.