vm

package
v1.0.5-0...-7826c6c Latest Latest
Warning

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

Go to latest
Published: Sep 22, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source
const (
	HookBeforeInstall = "before-install"
	HookAfterDownload = "after-download"
	HookAfterExtract  = "after-extract"
	HookAfterInstall  = "after-install"
)

Lifecycle events a tool can hook into. The installation reaches them in this order, and each one carries the values that exist by the time it is reached.

Variables

View Source
var DistFS embed.FS

DistFS embeds pre-bundled JS files from the dist directory.

View Source
var (
	LoaderPolyfills string
)
View Source
var LoaderPolyfillsRaw string

Functions

func HasHook

func HasHook(tool *config.ToolConfig, event string) bool

HasHook reports whether a tool registered any handler for an event. The loader records the event names alongside the tool's install parameters, so this answers without re-evaluating the tool file.

func HasResolver

func HasResolver(tool *config.ToolConfig, param string) bool

HasResolver reports whether the author gave a function for an install parameter.

A function cannot cross the JSON boundary the configuration takes to reach Go, so the loader records the parameter's name alongside the tool's install parameters and keeps the function itself in the VM. This answers from that record, without re-reading the tool file.

func LoadTypeScriptConfig

func LoadTypeScriptConfig(log *logger.Logger, fsys fs.FS, configPath string, opts ...Option) (*config.ProjectConfig, map[string]*config.ToolConfig, error)

LoadTypeScriptConfig loads and compiles a TypeScript config file and all tool configs dynamically, returning the unmarshaled ProjectConfig and map of ToolConfigs.

func RegisterBindings

func RegisterBindings(vm *goja.Runtime, target Target) error

RegisterBindings registers native Go utility functions and helper constants inside the Goja runtime, resolving platform-dependent values against target.

func RegisterContextBindings

func RegisterContextBindings(vm *goja.Runtime, log *logger.Logger, fsys fs.FS, homeDir string) error

RegisterContextBindings registers logging and filesystem bindings associated with the active execution environment.

homeDir is the home directory the project is configured with, which a tool configuration may deliberately point somewhere other than the invoking user's own -- a sandboxed home in a test project, for instance. Paths written with "~" resolve against it, so they land where the configuration says rather than where the process happens to be running. An empty homeDir leaves such paths untouched.

func ResolveInstallParam

func ResolveInstallParam(ctx context.Context, req ResolveRequest) (json.RawMessage, error)

ResolveInstallParam calls the function the author gave for an install parameter and returns what it produced, encoded as JSON for the installer to decode into the shape that parameter takes.

The tool's configuration file is evaluated again in a fresh VM, the same way a lifecycle hook is, because that is the only place the function still exists.

func RunHook

func RunHook(
	ctx context.Context,
	log *logger.Logger,
	fsys fs.FS,
	runner exec.CommandRunner,
	tool *config.ToolConfig,
	projCfg *config.ProjectConfig,
	event string,
	hookCtx HookContext,
	target Target,
) error

RunHook invokes the handlers a tool registered for a lifecycle event.

The tool's configuration file is re-evaluated in a fresh VM so the handler closure is available to call: a function cannot survive the JSON boundary the configuration crosses to reach Go. Re-evaluating is cheap next to an installation, and a VM per invocation keeps hooks from sharing mutable state with configuration loading or with each other.

Types

type HookContext

type HookContext struct {
	StagingDir   string
	DownloadPath string
	ExtractDir   string
	InstalledDir string
	BinaryPaths  []string
	Version      string
	// ExtractedFiles and Executables are what the extractor produced: every file it
	// unpacked, and the subset it marked executable. An after-extract hook placing a
	// binary reads them instead of walking the tree and repeating the heuristic.
	ExtractedFiles []string
	Executables    []string
	// Env is the environment commands run with. The orchestrator builds it so the
	// binaries a tool just installed are on PATH, letting a hook call them by name.
	Env []string
}

HookContext carries the values that only exist while an installation is under way. Fields left empty are omitted from the JavaScript context rather than being passed as empty strings, so a hook reading one that its event does not provide sees undefined instead of a plausible-looking wrong path.

type Option

type Option func(*loadOptions)

Option configures how a configuration is loaded.

func WithTarget

func WithTarget(target Target) Option

WithTarget evaluates platform-dependent configuration in tool files against the given target rather than the host. Empty fields fall back to the host. It backs the --platform, --arch and --libc flags.

type ResolveRequest

type ResolveRequest struct {
	Log     *logger.Logger
	FS      fs.FS
	Runner  exec.CommandRunner
	Tool    *config.ToolConfig
	ProjCfg *config.ProjectConfig
	Param   string
	Context map[string]any
	Target  Target
}

ResolveRequest describes one install parameter to compute.

Context carries the values that only exist once the installation is under way and that the parameter's own installer knows about -- the downloaded script's path, the release it is choosing an asset from. They are merged into the tool context the resolver receives, so a resolver reads the real path where the configuration, read long before, could only carry a placeholder.

type Target

type Target struct {
	OS   string
	Arch string
	Libc string
}

Target selects the OS, architecture and C library that platform-dependent configuration is evaluated against. Empty fields fall back to the host, so the zero Target means "this machine". It backs the --platform, --arch and --libc flags.

func (Target) Resolve

func (t Target) Resolve() Target

Resolve returns this target with every field named explicitly: what was left empty is filled in from the host, and the C library follows the resolved platform. A resolved target is what the command layer builds once from --platform/--arch/--libc and hands to configuration loading, to the installers and to the lifecycle hooks, so that one target governs the whole run.

Jump to

Keyboard shortcuts

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