jsenv

package
v0.0.0-...-f9c8925 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 14, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package jsenv bundles a TypeScript entrypoint with esbuild and evaluates it in a goja VM to produce the JSON IR (SPEC.md §5.1).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Discover

func Discover(dir string) ([]string, error)

Discover returns the project's TypeScript entry files in bundle order: dex.config.ts first, then every dex/services/**/*.ts and dex/commands/**/*.ts below dir as slash-separated paths relative to dir, sorted. dex.config.ts must exist — its absence is the "not a dex project" error, reported here rather than as an opaque esbuild resolve failure. A missing dex/services/ or dex/commands/ directory is fine (contributes nothing), and *.d.ts files and dot-prefixed directories (e.g. .git, .dex) are skipped. The registry and buildIR sort internally, so file order only makes the first error deterministic.

Types

type Bundler

type Bundler interface {
	Bundle(dir string, files []string) (string, error)
}

Bundler transpiles and bundles a project's TypeScript entry files into a single script runnable by an Evaluator.

type CommandInfo

type CommandInfo struct {
	Name        string
	Description string
}

CommandInfo describes one registered command for `dex run` listing.

type EsbuildBundler

type EsbuildBundler struct{}

EsbuildBundler bundles with esbuild, resolving the bare "@dex/iac" specifier to the SDK embedded in the binary.

func NewEsbuildBundler

func NewEsbuildBundler() *EsbuildBundler

NewEsbuildBundler returns a Bundler backed by esbuild.

func (*EsbuildBundler) Bundle

func (b *EsbuildBundler) Bundle(dir string, files []string) (string, error)

Bundle transpiles and bundles files (slash paths relative to dir) into a single IIFE script. Any bare import other than "@dex/iac" stays unresolvable and surfaces as an esbuild error — correct, since no package manager exists on the user machine.

type Evaluator

type Evaluator interface {
	Evaluate(ctx context.Context, script string, env map[string]string) ([]byte, error)
}

Evaluator runs a bundled script and returns the JSON IR produced by calling __dex_synth().

type ExecFunc

type ExecFunc func(ctx context.Context, argv []string) (int, error)

ExecFunc runs argv as a host process with stdio attached and returns its exit code. It must return an error only when the process could not be started; a process that ran and exited non-zero is a code, not an error.

type GojaEvaluator

type GojaEvaluator struct {
	// contains filtered or unexported fields
}

GojaEvaluator runs scripts in a goja ECMAScript VM.

func NewGojaEvaluator

func NewGojaEvaluator() *GojaEvaluator

NewGojaEvaluator returns an Evaluator with a 10s run budget.

func NewGojaEvaluatorWithTimeout

func NewGojaEvaluatorWithTimeout(d time.Duration) *GojaEvaluator

NewGojaEvaluatorWithTimeout returns an Evaluator with a custom run budget; a zero duration means no budget, so only ctx cancellation interrupts.

func (*GojaEvaluator) Evaluate

func (g *GojaEvaluator) Evaluate(ctx context.Context, script string, env map[string]string) ([]byte, error)

Evaluate runs script with env exposed as globalThis.__dex_env and returns the JSON string produced by calling globalThis.__dex_synth().

func (*GojaEvaluator) ListCommands

func (g *GojaEvaluator) ListCommands(ctx context.Context, script string, env map[string]string) ([]CommandInfo, error)

ListCommands evaluates script (env exposed as __dex_env) and returns the commands registered via the SDK's defineCommand, in registry order.

func (*GojaEvaluator) RunCommand

func (g *GojaEvaluator) RunCommand(ctx context.Context, script string, env map[string]string, name string, args []string, resources map[string]any, execFn ExecFunc) (int, error)

RunCommand evaluates script and calls the run() of the command named name with a ctx exposing args, env(key), resources (state exactly as persisted, secrets still hashed), secret(key) (plaintext from the same env map), and exec(argv) (a host process, via execFn), returning the command's numeric result as an exit code (0 when run returns undefined).

type Synthesizer

type Synthesizer struct {
	// contains filtered or unexported fields
}

Synthesizer turns a TypeScript entrypoint into raw IR JSON. Parsing and validating that JSON is the engine's job (SPEC.md §4 Step 2.1), not this TS-execution wrapper's: keeping it here would make pkg/jsenv depend on pkg/engine/ir while pkg/engine depends on pkg/jsenv, a loop back into the engine.

func NewSynthesizer

func NewSynthesizer(b Bundler, e Evaluator) *Synthesizer

NewSynthesizer wires a Bundler and Evaluator into a Synthesizer.

func (*Synthesizer) Synth

func (s *Synthesizer) Synth(ctx context.Context, dir string, env map[string]string) ([]byte, error)

Synth discovers dir's config files (dex.config.ts plus dex/services/** and dex/commands/**), bundles them, and evaluates the result with env exposed to the SDK's env() helper, returning the raw IR JSON bytes (SPEC.md §5.1).

Directories

Path Synopsis
sdk
Package sdk embeds the pre-bundled @dex/iac JavaScript so it ships inside the dex binary; the user has no Node.js and no node_modules.
Package sdk embeds the pre-bundled @dex/iac JavaScript so it ships inside the dex binary; the user has no Node.js and no node_modules.
gen command
Command gen bundles packages/sdk/dist (tsc output) into a single ESM file embedded into the dex binary as pkg/jsenv/sdk/iac.js.
Command gen bundles packages/sdk/dist (tsc output) into a single ESM file embedded into the dex binary as pkg/jsenv/sdk/iac.js.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL