Documentation
¶
Index ¶
- func FormatScriptDisplay(interpreter, script string) string
- func LookPath(dir string, env []string, name string) (string, error)
- func NewScriptCommand(ctx context.Context, spec *ScriptSpec) *exec.Cmd
- func NewShellCommand(ctx context.Context, command string) *exec.Cmd
- func ReplaceShellSession(spec *ExecSpec) error
- func RunScript(ctx context.Context, spec *ScriptSpec, stdout, stderr io.Writer) error
- func RunShellInterpreter(ctx context.Context, spec *ShellInterpreterSpec) error
- func RunShellSession(ctx context.Context, spec *ShellSessionSpec) error
- func RunShellStep(ctx context.Context, spec *ShellSessionSpec, plain func() error) error
- func ScriptInvocation(interpreter, script string) ([]string, io.Reader)
- type DefaultRunner
- type ExecSpec
- type Result
- type Runner
- type ScriptSpec
- type ShellInterpreterSpec
- type ShellSessionSpec
- type Streams
- type TaskSpec
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FormatScriptDisplay ¶ added in v1.223.0
FormatScriptDisplay returns a readable command preview for show.command.
func LookPath ¶
LookPath resolves name to an executable using the PATH (and, on Windows, PATHEXT) found in env rather than the process environment, so callers see exactly what a process started with that env would run. Names containing a path separator resolve relative to dir. It returns an error when nothing executable matches.
func NewScriptCommand ¶ added in v1.223.0
func NewScriptCommand(ctx context.Context, spec *ScriptSpec) *exec.Cmd
NewScriptCommand builds an exec.Cmd for a script invocation.
func NewShellCommand ¶ added in v1.226.0
NewShellCommand builds the system-shell invocation for a session command string: `sh -c <command>`. Callers must pass only command strings authored in trusted configuration (e.g. atmos.yaml) -- command is interpolated into a real shell invocation with no escaping of its own.
func ReplaceShellSession ¶ added in v1.222.0
ReplaceShellSession replaces the Atmos process with the spec's command (execve of the system shell). On success it never returns: the command inherits the terminal, file descriptors, environment, and working directory, and its exit code becomes the process exit code natively. It returns an error only if the replacement could not be performed (or nil for dry-run).
func RunScript ¶ added in v1.223.0
RunScript executes an inline script with attached output streams.
func RunShellInterpreter ¶
func RunShellInterpreter(ctx context.Context, spec *ShellInterpreterSpec) error
RunShellInterpreter runs a shell script in-process with mvdan.cc/sh and starts every external command it runs through the process runner. Each command is therefore the leader of its own process group (unless it inherits a terminal), and cancelling ctx, for example when a step `timeout:` expires, sends SIGTERM to the whole group and SIGKILL to survivors after a grace period. The interpreter's default command handler signals only the direct child, which leaves the grandchildren of `sh -c 'worker & wait'` running. On Windows only the direct child is terminated, as everywhere else in this package.
A non-zero exit becomes errUtils.ExitCodeError so callers can propagate the child's exit code.
func RunShellSession ¶ added in v1.222.0
func RunShellSession(ctx context.Context, spec *ShellSessionSpec) error
RunShellSession executes a shell command attached to the user's terminal.
When TTY is set and the platform supports it, the command runs under a pseudo-terminal: output masking is preserved, and (with Interactive) the host terminal switches to raw mode so Ctrl-C reaches the child instead of Atmos. Otherwise the command inherits the real stdin/stdout/stderr file descriptors directly; masking is unavailable in that mode.
Non-zero exits are returned as errUtils.ExitCodeError.
func RunShellStep ¶ added in v1.222.0
func RunShellStep(ctx context.Context, spec *ShellSessionSpec, plain func() error) error
RunShellStep routes a shell-family step: steps that request a terminal (tty and/or interactive) run as terminal-attached sessions; plain steps run via the caller-provided fallback (each execution path keeps its own plain-step behavior: masked interpreter, command runner, output modes).
Types ¶
type ExecSpec ¶ added in v1.222.0
type ExecSpec struct {
// Command is the raw shell command string, run via the system shell.
Command string
// Name is a logical name used for logging.
Name string
// Dir is the working directory to change to before the replacement ("" keeps the current directory).
Dir string
// Env is the fully merged environment, used verbatim. ATMOS_SHLVL is NOT
// incremented: the session replaces Atmos rather than nesting under it.
Env []string
// DryRun logs the command without executing it.
DryRun bool
}
ExecSpec describes an exec step: a command that replaces the Atmos process entirely (shell exec semantics). Exec steps must be the final step — nothing runs after the replacement, and supervisor features (masking, output capture, retry, timeout) do not apply.
type Result ¶
type Result struct {
Command string
Args []string
ExitCode int
Err error
Started bool
Canceled bool
Signaled bool
Signal string
SignalNumber int
StartedAt time.Time
FinishedAt time.Time
// Metrics captures the subprocess tree's (this command plus any children,
// e.g. terraform plus its provider plugins) resource usage, collected
// from cmd.ProcessState once cmd.Wait() returns. Nil when the process
// never started (e.g. cmd.Start() failed or DryRun was set).
Metrics *metricsprocess.ProcessMetrics
}
Result contains the outcome of a subprocess invocation.
type Runner ¶
Runner executes a task and returns the observed process result.
func NewDefaultRunner ¶
func NewDefaultRunner() Runner
NewDefaultRunner returns a Runner backed by os/exec.
type ScriptSpec ¶ added in v1.223.0
type ScriptSpec struct {
Interpreter string
Script string
Name string
Dir string
Env []string
DryRun bool
}
ScriptSpec describes an inline script executed by a named interpreter.
type ShellInterpreterSpec ¶
type ShellInterpreterSpec struct {
// Command is the shell script.
Command string
// Name labels the script in parse errors.
Name string
// Dir is the working directory.
Dir string
// Env is the environment. When empty, os.Environ() is used.
Env []string
// Params are the script's positional parameters ($1, $2, "$@"). Git hook arguments reach
// shell steps this way.
Params []string
// Stdin is the script's standard input. When nil, os.Stdin is used.
Stdin io.Reader
// Stdout and Stderr receive the script's output.
Stdout io.Writer
Stderr io.Writer
}
ShellInterpreterSpec describes a shell script run by the in-process mvdan/sh interpreter.
type ShellSessionSpec ¶ added in v1.222.0
type ShellSessionSpec struct {
// Command is the raw shell command string, run via the system shell.
Command string
// Name is a logical name used for logging.
Name string
// Dir is the working directory.
Dir string
// Env is the fully merged environment. When empty, os.Environ() is used.
Env []string
// TTY allocates a pseudo-terminal when the platform supports it.
TTY bool
// Interactive forwards host stdin to the session and suspends the Atmos
// SIGINT-exit handler so Ctrl-C is handled by the child process.
Interactive bool
// DryRun logs the command without executing it.
DryRun bool
// Masker applies secret masking to PTY output. When nil, it defaults to
// iolib.GetContext().Masker() with EnableMasking from the `mask` setting,
// so call sites don't need masking wiring.
Masker iolib.Masker
// EnableMasking enables secret masking of session output where supported.
EnableMasking bool
}
ShellSessionSpec describes a shell step that attaches to the user's terminal (steps declared with `tty: true` and/or `interactive: true`).
type TaskSpec ¶
type TaskSpec struct {
Command string
Args []string
Dir string
Env []string
Streams Streams
DryRun bool
// SkipMetrics leaves the subprocess's resource usage out of the end-of-invocation summary.
// Steps that report their own result, such as shell and atmos steps, set it so running them
// through the runner does not add a "Total for this invocation" line they never printed.
SkipMetrics bool
}
TaskSpec describes a subprocess invocation.
Source Files