Documentation
¶
Index ¶
- Constants
- Variables
- func HasHook(tool *config.ToolConfig, event string) bool
- func HasResolver(tool *config.ToolConfig, param string) bool
- func LoadTypeScriptConfig(log *logger.Logger, fsys fs.FS, configPath string, opts ...Option) (*config.ProjectConfig, map[string]*config.ToolConfig, error)
- func RegisterBindings(vm *goja.Runtime, target Target) error
- func RegisterContextBindings(vm *goja.Runtime, log *logger.Logger, fsys fs.FS, homeDir string) error
- func ResolveInstallParam(ctx context.Context, req ResolveRequest) (json.RawMessage, error)
- func RunHook(ctx context.Context, log *logger.Logger, fsys fs.FS, runner exec.CommandRunner, ...) error
- type HookContext
- type Option
- type ResolveRequest
- type Target
Constants ¶
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 ¶
var DistFS embed.FS
DistFS embeds pre-bundled JS files from the dist directory.
var (
LoaderPolyfills string
)
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 ¶
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 ¶
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 ¶
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 ¶
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.