1package shell
2
3import (
4 "context"
5 "fmt"
6 "io"
7 "strings"
8
9 "mvdan.cc/sh/moreinterp/coreutils"
10 "mvdan.cc/sh/v3/expand"
11 "mvdan.cc/sh/v3/interp"
12 "mvdan.cc/sh/v3/syntax"
13)
14
15// RunOptions configures a single stateless shell execution via [Run].
16//
17// The zero value is not useful; at minimum Command must be set. Stdin,
18// Stdout, and Stderr may be nil (nil readers/writers are treated as
19// empty/discard). BlockFuncs may be nil to disable block-list enforcement —
20// hooks use this to run user-authored commands with the same trust level as
21// a shell alias.
22type RunOptions struct {
23 // Command is the shell source to parse and execute.
24 Command string
25 // Cwd is the working directory for the execution. Required: callers
26 // must supply a non-empty value. Run does not silently fall back to
27 // the Crush process cwd — hooks and the bash tool have different
28 // notions of "default" and each owns that decision.
29 Cwd string
30 // Env is the full environment visible to the command. The caller is
31 // responsible for inheriting from os.Environ() if that's desired.
32 Env []string
33 // Stdin is the command's standard input. nil is equivalent to an empty
34 // input stream.
35 Stdin io.Reader
36 // Stdout receives the command's standard output. nil discards output.
37 Stdout io.Writer
38 // Stderr receives the command's standard error. nil discards output.
39 Stderr io.Writer
40 // BlockFuncs is an optional list of deny-list matchers applied before
41 // each command reaches the exec layer. nil disables blocking entirely.
42 BlockFuncs []BlockFunc
43}
44
45// Run parses and executes a shell command using the same mvdan.cc/sh
46// interpreter stack that the stateful [Shell] type uses (builtins,
47// optional block list, optional Go coreutils). It is safe to call
48// concurrently from multiple goroutines: each call builds its own
49// [interp.Runner] and shares no state with other callers or with any
50// [Shell] instance.
51//
52// Errors returned from the command itself (non-zero exit, context
53// cancellation, parse failures) follow the same conventions as
54// [Shell.Exec]: inspect with [IsInterrupt] and [ExitCode].
55func Run(ctx context.Context, opts RunOptions) (err error) {
56 defer func() {
57 if r := recover(); r != nil {
58 err = fmt.Errorf("command execution panic: %v", r)
59 }
60 }()
61
62 if opts.Cwd == "" {
63 return fmt.Errorf("shell.Run: Cwd is required")
64 }
65
66 stdout := opts.Stdout
67 if stdout == nil {
68 stdout = io.Discard
69 }
70 stderr := opts.Stderr
71 if stderr == nil {
72 stderr = io.Discard
73 }
74
75 line, err := syntax.NewParser().Parse(strings.NewReader(opts.Command), "")
76 if err != nil {
77 return fmt.Errorf("could not parse command: %w", err)
78 }
79
80 runner, err := newRunner(opts.Cwd, opts.Env, opts.Stdin, stdout, stderr, opts.BlockFuncs)
81 if err != nil {
82 return fmt.Errorf("could not run command: %w", err)
83 }
84
85 return runner.Run(ctx, line)
86}
87
88// newRunner constructs an [interp.Runner] configured with the standard
89// Crush handler stack. Shared by the stateless [Run] entrypoint and the
90// stateful [Shell] so the two surfaces cannot drift.
91func newRunner(cwd string, env []string, stdin io.Reader, stdout, stderr io.Writer, blockFuncs []BlockFunc) (*interp.Runner, error) {
92 return interp.New(
93 interp.StdIO(stdin, stdout, stderr),
94 interp.Interactive(false),
95 interp.Env(expand.ListEnviron(env...)),
96 interp.Dir(cwd),
97 interp.ExecHandlers(standardHandlers(blockFuncs)...),
98 )
99}
100
101// standardHandlers returns the exec-handler middleware chain used by both
102// [Run] and [Shell]. Order matters: builtins first (so Crush's in-process
103// jq wins over any PATH binary), then the block list, then optional Go
104// coreutils. Future middleware (shebang dispatch, etc.) inserts here.
105func standardHandlers(blockFuncs []BlockFunc) []func(next interp.ExecHandlerFunc) interp.ExecHandlerFunc {
106 handlers := []func(next interp.ExecHandlerFunc) interp.ExecHandlerFunc{
107 builtinHandler(),
108 blockHandler(blockFuncs),
109 }
110 if useGoCoreUtils {
111 handlers = append(handlers, coreutils.ExecHandler)
112 }
113 return handlers
114}
115
116// builtinHandler returns middleware that dispatches recognized Crush
117// builtins to their in-process Go implementations. Currently: jq.
118func builtinHandler() func(next interp.ExecHandlerFunc) interp.ExecHandlerFunc {
119 return func(next interp.ExecHandlerFunc) interp.ExecHandlerFunc {
120 return func(ctx context.Context, args []string) error {
121 if len(args) == 0 {
122 return next(ctx, args)
123 }
124 switch args[0] {
125 case "jq":
126 hc := interp.HandlerCtx(ctx)
127 return handleJQ(args, hc.Stdin, hc.Stdout, hc.Stderr)
128 default:
129 return next(ctx, args)
130 }
131 }
132 }
133}
134
135// blockHandler returns middleware that rejects commands matched by any of
136// the provided [BlockFunc]s before they reach the underlying exec path.
137// A nil or empty blockFuncs slice is a no-op.
138func blockHandler(blockFuncs []BlockFunc) func(next interp.ExecHandlerFunc) interp.ExecHandlerFunc {
139 return func(next interp.ExecHandlerFunc) interp.ExecHandlerFunc {
140 return func(ctx context.Context, args []string) error {
141 if len(args) == 0 {
142 return next(ctx, args)
143 }
144 for _, blockFunc := range blockFuncs {
145 if blockFunc(args) {
146 return fmt.Errorf("command is not allowed for security reasons: %q", args[0])
147 }
148 }
149 return next(ctx, args)
150 }
151 }
152}