feat(bundler): optional RuntimeFile prepends a runtime-entry import via stdin

internal/bundler/bundler.go

@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"path/filepath"
 	"strings"
 
 	esbuild "github.com/evanw/esbuild/pkg/api"
@@ -13,9 +14,14 @@ import (
 
 type Options struct {
 	EntryFile string
-	Defines   map[string]string
+	// RuntimeFile, when set, is imported BEFORE the spec via a stdin entry so
-	Aliases   map[string]string
+	// the bundle installs __sanderlingNextAction__ / __sanderlingExtractors__
-	Sourcemap bool
+	// (the goja runtime entry wires the shared picker). Empty bundles the spec
+	// alone, as the bundle-check tool and unit fixtures do.
+	RuntimeFile string
+	Defines     map[string]string
+	Aliases     map[string]string
+	Sourcemap   bool
 }
 
 type Result struct {
@@ -45,18 +51,36 @@ func Bundle(options Options) (Result, error) {
 		sourcemap = esbuild.SourceMapInline
 	}
 
-	output := esbuild.Build(esbuild.BuildOptions{
+	buildOptions := esbuild.BuildOptions{
-		EntryPoints: []string{options.EntryFile},
+		Bundle:    true,
-		Bundle:      true,
+		Format:    esbuild.FormatIIFE,
-		Format:      esbuild.FormatIIFE,
+		Target:    esbuild.ES2020,
-		Target:      esbuild.ES2020,
+		Platform:  esbuild.PlatformNeutral,
-		Platform:    esbuild.PlatformNeutral,
+		Define:    defines,
-		Define:      defines,
+		Alias:     options.Aliases,
-		Alias:       options.Aliases,
+		Sourcemap: sourcemap,
-		Sourcemap:   sourcemap,
+		Write:     false,
-		Write:       false,
+		LogLevel:  esbuild.LogLevelSilent,
-		LogLevel:    esbuild.LogLevelSilent,
+	}
-	})
+	if options.RuntimeFile == "" {
+		buildOptions.EntryPoints = []string{options.EntryFile}
+	} else {
+		runtimeAbs, err := filepath.Abs(options.RuntimeFile)
+		if err != nil {
+			return Result{}, fmt.Errorf("runtime path: %w", err)
+		}
+		specAbs, err := filepath.Abs(options.EntryFile)
+		if err != nil {
+			return Result{}, fmt.Errorf("entry path: %w", err)
+		}
+		buildOptions.Stdin = &esbuild.StdinOptions{
+			Contents:   fmt.Sprintf("import %q;\nimport %q;\n", runtimeAbs, specAbs),
+			ResolveDir: filepath.Dir(specAbs),
+			Loader:     esbuild.LoaderTS,
+		}
+	}
+
+	output := esbuild.Build(buildOptions)
 
 	if len(output.Errors) > 0 {
 		var messages []string