recipe

package
v0.0.0-...-0f32820 Latest Latest
Warning

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

 Go to latest Published: Aug 22, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	GoProfile   = "go"
	NodeProfile = "node"
	RustProfile = "rust"
)
View Source 
const (
	GoPackageValuesCommand     = "@go-packages"
	GoFmtTargetValuesCommand   = `@go-packages; @glob "*.go"`
	GoMainPackageValuesCommand = "@go-main-packages"
	GoModuleValuesCommand      = "@go-modules"
	GoRunCommandValuesCommand  = GoMainPackageValuesCommand + `; @glob "*.go"`
)
View Source 
const (
	ForEachItemPlaceholder      = "item"
	ForEachItemHelpPlaceholder  = "item_help"
	ForEachItemIndexPlaceholder = "item_index"
	RunIDPlaceholder            = "run_id"
	StatusPlaceholder           = "status"
	PresetArgumentName          = "preset"
)
View Source 
const (
	LogStagePre  = "pre"
	LogStageCmd  = "cmd"
	LogStagePost = "post"
)
View Source 
const (
	RustToolchainDefault = "shadowtree-default"
	RustToolchainFile    = "rust-toolchain"
	RustToolchainTOML    = "rust-toolchain.toml"
)
View Source 
const DefaultRustToolchain = "1.96.0"
View Source 
const RetryCommandHelper = "retry"

RetryCommandHelper is the built-in @ command helper that retries another command.

View Source 
const RustTargetCacheConcurrency = "exclusive"

Variables

View Source 
var ReservedNames = map[string]bool{
	"recipes":          true,
	"init":             true,
	"config":           true,
	"exec":             true,
	"completion":       true,
	"help":             true,
	"version":          true,
	"__complete":       true,
	RetryCommandHelper: true,
}

Functions

func AllSupport 

func AllSupport(rec Recipe) (domain, unsupported string, supported bool)

AllSupport reports how --all applies to rec.

func ApplyGlobalsExpanded 

func ApplyGlobalsExpanded(recipes map[string]Recipe, vars, dynamicVars map[string]string, shell, shellPrelude string) (map[string]Recipe, error)

ApplyGlobalsExpanded applies globals after expanding static vars.

func ArgumentHasEnumValues 

func ArgumentHasEnumValues(arg Argument) bool

ArgumentHasEnumValues reports whether arg is constrained by static enum values, directly or through @enum_set.

func ArgumentHelp 

func ArgumentHelp(arg Argument) string

func ArgumentType 

func ArgumentType(arg Argument) string

ArgumentType reports arg.Type with Shadowtree's default type applied.

func BuiltinReferenceDetail 

func BuiltinReferenceDetail(name string) string

BuiltinReferenceDetail returns editor/help detail for a built-in @ command.

func BuiltinReferenceNames 

func BuiltinReferenceNames() []string

BuiltinReferenceNames returns built-in @ command names usable for argument values.

func BuiltinStatus 

func BuiltinStatus(rec Recipe) (builtin, overridden bool)

BuiltinStatus reports whether rec comes from a profile and whether project configuration overrides that profile recipe.

func Builtins 

func Builtins(profile string, opts BuiltinOptions) map[string]Recipe

func CommandContainsStageStatusPlaceholder 

func CommandContainsStageStatusPlaceholder(command Command) bool

CommandContainsStageStatusPlaceholder reports whether command contains a stage status placeholder.

func CommandHelpText 

func CommandHelpText(command Command) string

func CommandOutput 

func CommandOutput(ctx context.Context, dir string, env map[string]string, command Command) (string, error)

func CommandSummary 

func CommandSummary(rec Recipe) string

func EffectiveLogStages 

func EffectiveLogStages(rec Recipe) []string

func EvalVarCommands 

func EvalVarCommands(ctx context.Context, dir string, env map[string]string, commands map[string]Command, shell, shellPrelude string) (map[string]string, error)

func ExpandForEachString 

func ExpandForEachString(value string, item ValueCandidate, index int) (string, error)

ExpandForEachString expands for_each placeholders in value.

func Help 

func Help(rec Recipe) string

func Invocation 

func Invocation(rest []string) (string, []string)

func IsBuiltinReferenceName 

func IsBuiltinReferenceName(name string) bool

IsBuiltinReferenceName reports whether name identifies a built-in @ command.

func IsCommandHelperName 

func IsCommandHelperName(name string) bool

IsCommandHelperName reports whether name identifies a built-in @ command helper.

func IsRecipeReferenceString 

func IsRecipeReferenceString(value string) bool

IsRecipeReferenceString reports whether value is exactly an @recipe script string.

func IsReservedRecipeName 

func IsReservedRecipeName(name string) bool

IsReservedRecipeName reports whether name cannot be used for a recipe.

func IsScriptCommand 

func IsScriptCommand(command Command) bool

func IsStageCommandField 

func IsStageCommandField(name string) bool

IsStageCommandField reports whether name is a supported structured stage command field.

func IsStageStatusPlaceholder 

func IsStageStatusPlaceholder(placeholder Placeholder) bool

IsStageStatusPlaceholder reports whether placeholder references a prior stage status.

func JoinShell 

func JoinShell(parts ...string) string

JoinShell joins shell prelude parts using Shadowtree's runtime shell semantics.

func MergeRecipes 

func MergeRecipes(base, overrides map[string]Recipe) (map[string]Recipe, error)

func NewRunID 

func NewRunID() (string, error)

func NodeInstallCommandForPackageManager 

func NodeInstallCommandForPackageManager(pm, pkg string) string

NodeInstallCommandForPackageManager returns package-manager-specific guidance for installing a recipe-required Node CLI package.

func NodePackageManager 

func NodePackageManager(dir string) string

NodePackageManager reports the package manager Shadowtree detects from dir.

func PlaceholderSurroundingQuote 

func PlaceholderSurroundingQuote(text string, start, end int) byte

PlaceholderSurroundingQuote reports a quote that directly wraps one placeholder.

func PositionalArguments 

func PositionalArguments(args map[string]Argument) []string

func RecipeSandboxed 

func RecipeSandboxed(rec Recipe) bool

func RecipeUsesVariadicArgs 

func RecipeUsesVariadicArgs(rec Recipe) bool

RecipeUsesVariadicArgs reports whether rec references the leftover CLI args placeholder.

func RustToolchain 

func RustToolchain(dir string) (string, error)

RustToolchain validates the project marker and returns the selected exact toolchain without invoking Cargo.

func ScalarValueString 

func ScalarValueString(value any) (string, error)

ScalarValueString converts a TOML scalar value to its argument string form.

func ScriptBody 

func ScriptBody(command Command) string

func ScriptPlaceholderQuoteContexts 

func ScriptPlaceholderQuoteContexts(text, shell string) (map[int]byte, error)

ScriptPlaceholderQuoteContexts reports quote context for script placeholders.

func ScriptShell 

func ScriptShell(command Command) string

func SelectAll 

func SelectAll(name string, rec Recipe) (Recipe, string, TargetSource, error)

SelectAll selects rec's complete aggregate alternative.

func SingleLine 

func SingleLine(text string) string

func StageAllowsStatusPlaceholder 

func StageAllowsStatusPlaceholder(commandStage string, placeholder Placeholder) bool

StageAllowsStatusPlaceholder reports whether placeholder is available in commandStage.

func StageCommandHelpText 

func StageCommandHelpText(command StageCommand) string

StageCommandHelpText returns a compact display form for command.

func StageTimeout 

func StageTimeout(command StageCommand) time.Duration

StageTimeout returns the resolved timeout for command, or zero when unset.

func StatusPlaceholderContextError 

func StatusPlaceholderContextError(placeholder Placeholder) error

StatusPlaceholderContextError reports where a status placeholder may be used.

func StatusPlaceholderStages 

func StatusPlaceholderStages(commandStage string) []string

StatusPlaceholderStages reports which status placeholders are available in commandStage.

func SupportsProfile 

func SupportsProfile(profile string) bool

func ValidLogStage 

func ValidLogStage(stage string) bool

func ValidPlaceholderMode 

func ValidPlaceholderMode(mode PlaceholderMode) bool

ValidPlaceholderMode reports whether mode is supported.

func ValidateArgumentAcceptedValue 

func ValidateArgumentAcceptedValue(name string, arg Argument, value string, opts ValueBuiltinOptions) error

ValidateArgumentAcceptedValue validates value against arg.Values when the values provider can be evaluated safely during argument resolution.

func ValidateArgumentValue 

func ValidateArgumentValue(name string, arg Argument, value string) error

ValidateArgumentValue validates a string argument value's scalar type and range.

func ValidateArguments 

func ValidateArguments(args map[string]Argument) error

func ValidateCommand 

func ValidateCommand(command Command) error

func ValidateConfig 

func ValidateConfig(cfg Config) error

func ValidateEnumSetReferences 

func ValidateEnumSetReferences(cfg Config) error

ValidateEnumSetReferences validates named enum references after config includes merge.

func ValidateLogSettings 

func ValidateLogSettings(name string, rec Recipe) error

func ValidatePlaceholderMode 

func ValidatePlaceholderMode(placeholder Placeholder, shell bool, quote byte) error

ValidatePlaceholderMode reports whether placeholder may be used in the given context.

func ValidatePresetSelection 

func ValidatePresetSelection(rec Recipe, selectedPreset, value string) error

ValidatePresetSelection validates a preset=<name> selector against a recipe.

func ValidateResolvedRecipes 

func ValidateResolvedRecipes(recipes map[string]Recipe) error

func ValidateStageCommand 

func ValidateStageCommand(command StageCommand) error

ValidateStageCommand validates a pre/post stage command.

func ValidateStageStatusPlaceholder 

func ValidateStageStatusPlaceholder(placeholder Placeholder) error

ValidateStageStatusPlaceholder reports whether placeholder is a supported stage status placeholder.

func ValidateValueBuiltin 

func ValidateValueBuiltin(command Command) (string, bool, error)

func ValueBuiltinUsesFilesystem 

func ValueBuiltinUsesFilesystem(command Command) (bool, bool, error)

ValueBuiltinUsesFilesystem reports whether command is a filesystem-backed value builtin.

Types

type Argument 

type Argument struct {
	Help     string  `toml:"help"`
	Type     string  `toml:"type"`
	PathKind string  `toml:"path_kind"`
	Position int     `toml:"position"`
	Required bool    `toml:"required"`
	Default  any     `toml:"default"`
	Min      any     `toml:"min"`
	Max      any     `toml:"max"`
	Values   Command `toml:"values"`
}

func MergeArgument 

func MergeArgument(base, override Argument) Argument

type BuiltinOptions 

type BuiltinOptions struct {
	Context       context.Context
	Dir           string
	RustToolchain string
}

type Command 

type Command []string

func CommandWithRecipeReference 

func CommandWithRecipeReference(command Command, shell, shellPrelude string) Command

func CommandWithRecipeReferenceExpandedPrelude 

func CommandWithRecipeReferenceExpandedPrelude(command Command, shell, shellPrelude string, values map[string]string) (Command, error)

CommandWithRecipeReferenceExpandedPrelude expands placeholders in shellPrelude only when command will consume the prelude, then applies recipe-reference and shell wrapping.

func CommandWithShell 

func CommandWithShell(command Command, shell, shellPrelude string) Command

func ExpandForEachCommand 

func ExpandForEachCommand(command Command, item ValueCandidate, index int) (Command, error)

ExpandForEachCommand expands for_each placeholders in command.

func ExpandStageStatusPlaceholders 

func ExpandStageStatusPlaceholders(command Command, values map[string]string) (Command, error)

ExpandStageStatusPlaceholders expands prior-stage status placeholders in a command.

func ScriptCommand 

func ScriptCommand(script string) Command

func ShellCommand 

func ShellCommand(command Command) Command

func (*Command) UnmarshalTOML 

func (command *Command) UnmarshalTOML(value any) error

type Config 

type Config struct {
	Include      []string           `toml:"include"`
	Profile      string             `toml:"profile"`
	Env          map[string]string  `toml:"env"`
	Vars         map[string]string  `toml:"vars"`
	VarCommands  map[string]Command `toml:"var_commands"`
	EnumSets     map[string]Command `toml:"enum_sets"`
	Shell        string             `toml:"shell"`
	ShellPrelude string             `toml:"shell_prelude"`
	Recipes      map[string]Recipe  `toml:"recipes"`
}

type ConfigErrorTarget 

type ConfigErrorTarget string
const (
	ConfigErrorTargetValue ConfigErrorTarget = "value"
	ConfigErrorTargetKey   ConfigErrorTarget = "key"
	ConfigErrorTargetTable ConfigErrorTarget = "table"
)

type ConfigPathError 

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

ConfigPathError reports the TOML config path associated with a validation error.

func (*ConfigPathError) ConfigPath 

func (err *ConfigPathError) ConfigPath() []string

func (*ConfigPathError) Error 

func (err *ConfigPathError) Error() string

func (*ConfigPathError) Target 

func (err *ConfigPathError) Target() ConfigErrorTarget

func (*ConfigPathError) Unwrap 

func (err *ConfigPathError) Unwrap() error

type ExecutionTarget 

type ExecutionTarget struct {
	Label   string
	Value   string
	Workdir string
}

ExecutionTarget is one aggregate main-command invocation.

func ResolveExecutionTargets 

func ResolveExecutionTargets(ctx context.Context, source TargetSource, dir string, env, buildArgs []string) ([]ExecutionTarget, error)

ResolveExecutionTargets discovers aggregate targets in the active workspace.

type Placeholder 

type Placeholder struct {
	Name  string
	Mode  PlaceholderMode
	Start int
	End   int
	Match string
}

Placeholder is a parsed {name} or {name:mode} reference.

func ParsePlaceholderAt 

func ParsePlaceholderAt(text string, start int) (Placeholder, bool)

ParsePlaceholderAt parses a Shadowtree placeholder starting at start.

type PlaceholderMode 

type PlaceholderMode string

PlaceholderMode controls how a Shadowtree placeholder is expanded. 

const (
	PlaceholderModeDefault PlaceholderMode = ""
	PlaceholderModeShell   PlaceholderMode = "shell"
	PlaceholderModeRaw     PlaceholderMode = "raw"
	PlaceholderModeDQ      PlaceholderMode = "dq"
)

type Recipe 

type Recipe struct {
	Help         string                  `toml:"help"`
	Arguments    map[string]Argument     `toml:"arguments"`
	Presets      map[string]RecipePreset `toml:"presets"`
	Requires     Requirements            `toml:"requires"`
	Vars         map[string]string       `toml:"vars"`
	Shell        string                  `toml:"shell"`
	ShellPrelude string                  `toml:"shell_prelude"`
	Sandboxed    *bool                   `toml:"sandboxed"`
	ForEach      Command                 `toml:"for_each"`
	Workdir      string                  `toml:"workdir"`
	Cmd          Command                 `toml:"cmd"`
	Pre          StageCommands           `toml:"pre"`
	Post         StageCommands           `toml:"post"`
	Env          map[string]string       `toml:"env"`
	SyncOut      []string                `toml:"sync_out"`
	Log          string                  `toml:"log"`
	LogStages    []string                `toml:"log_stages"`
	LogTee       *bool                   `toml:"log_tee"`
	// contains filtered or unexported fields
}

func MergeRecipe 

func MergeRecipe(base, override Recipe) Recipe

type RecipePreset 

type RecipePreset struct {
	Arguments map[string]any `toml:"arguments"`
}

RecipePreset sets argument defaults selected with preset=<name>.

type RecipeReferenceTarget 

type RecipeReferenceTarget struct {
	Path string
	Name string
	Args []string
}

RecipeReferenceTarget is a parsed @recipe or @path:recipe command target.

func ParseRecipeReference 

func ParseRecipeReference(command Command) (RecipeReferenceTarget, bool)

ParseRecipeReference parses a command whose first item starts with @.

func (RecipeReferenceTarget) Target 

func (ref RecipeReferenceTarget) Target() string

type Requirements 

type Requirements struct {
	Commands         []string          `toml:"commands"`
	OptionalCommands []string          `toml:"optional_commands"`
	GoCommands       map[string]string `toml:"go_commands"`
	NodeCommands     map[string]string `toml:"node_commands"`
}

Requirements declares external tools a recipe expects before commands run.

func (Requirements) Empty 

func (req Requirements) Empty() bool

Empty reports whether req declares no requirements.

type ResolveOptions 

type ResolveOptions struct {
	RunID        string
	Recipes      map[string]Recipe
	EnumSets     map[string]Command
	Scope        Scope
	TargetDomain string
	TargetSource TargetSource
}

type Resolved 

type Resolved struct {
	Name         string
	Recipe       Recipe
	Main         Command
	Preset       string
	Arguments    map[string]string
	VariadicArgs []string
	SyncOut      []string
	Sandboxed    bool
	GlobalEnv    map[string]string
	ConfigPath   string
	Profile      string
	RunID        string
	LogPath      string
	LogStages    []string
	LogTee       bool
	Warnings     []string
	Scope        Scope
	TargetDomain string
	TargetSource TargetSource
}

func Resolve 

func Resolve(name string, rec Recipe, cliArgs, globalSyncOut []string, globalEnv map[string]string, configPath, profile string) (Resolved, error)

func ResolveWithOptions 

func ResolveWithOptions(name string, rec Recipe, cliArgs, globalSyncOut []string, globalEnv map[string]string, configPath, profile string, opts ResolveOptions) (Resolved, error)

type RustProject 

type RustProject struct {
	WorkspaceRoot          string
	RootManifest           string
	MemberManifests        []string
	Lockfile               string
	Toolchain              string
	ToolchainProvenance    string
	CompilerCommit         string
	HostTriple             string
	TargetTriple           string
	CargoHome              string
	RegistryCache          string
	GitCache               string
	TargetDir              string
	ProjectCacheKey        string
	LockedPreparation      bool
	FetchCommand           Command
	CacheCompatibility     []string
	TargetCacheConcurrency string
}

RustProject is the canonical Cargo and toolchain metadata consumed by Rust recipes and sandbox providers.

func ResolveRustProject 

func ResolveRustProject(ctx context.Context, dir string, env, buildArgs []string) (RustProject, error)

ResolveRustProject resolves one Cargo workspace/package and exact toolchain. env is the invocation environment used for Cargo/rustc and target selection.

type Scope 

type Scope string

Scope identifies the user-selected execution scope. 

const ScopeAll Scope = "all"

type StageCommand 

type StageCommand struct {
	Cmd     Command `toml:"cmd"`
	Timeout string  `toml:"timeout"`
}

StageCommand is a pre/post command plus optional execution controls.

func (*StageCommand) UnmarshalTOML 

func (stage *StageCommand) UnmarshalTOML(value any) error

type StageCommands 

type StageCommands []StageCommand

StageCommands is the TOML representation of a pre or post command list.

func (*StageCommands) UnmarshalTOML 

func (commands *StageCommands) UnmarshalTOML(value any) error

type TargetSource 

type TargetSource string

TargetSource identifies a built-in provider of aggregate execution targets. 

const (
	GoPackageTargets     TargetSource = "go-packages"
	GoMainPackageTargets TargetSource = "go-main-packages"
	GoModuleTargets      TargetSource = "go-modules"
	RustWorkspaceTargets TargetSource = "rust-workspace"
)

type ValueBuiltinOptions 

type ValueBuiltinOptions struct {
	Context     context.Context
	Dir         string
	ConfigPath  string
	Recipe      Recipe
	Recipes     map[string]Recipe
	EnumSets    map[string]Command
	ValuePrefix string
}

type ValueCandidate 

type ValueCandidate struct {
	Value string
	Help  string
}

func BuiltinValues 

func BuiltinValues(command Command, opts ValueBuiltinOptions) ([]ValueCandidate, bool, error)

func ParseValueCandidateBytes 

func ParseValueCandidateBytes(output []byte, prefix string) []ValueCandidate

ParseValueCandidateBytes parses command output bytes in value<TAB>help format.

func ParseValueCandidates 

func ParseValueCandidates(output string) []ValueCandidate

ParseValueCandidates parses command output lines in value<TAB>help format.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.