Skip to main content

tinyharness_lib/custom_tools/
shell.rs

1use std::collections::HashMap;
2
3use serde::{Deserialize, Serialize};
4use tokio::io::AsyncReadExt;
5
6/// A shell command with template substitution and timeout.
7///
8/// The `command` field is a template string with `{var}` placeholders.
9/// At execution time, the placeholders are replaced with values from a
10/// `HashMap<String, String>`. The command is run via `sh -c` (or `cmd /C`
11/// on Windows) with the substituted variables also available as `TH_*`
12/// environment variables.
13///
14/// This type backs the custom-tools system: each custom tool wraps a
15/// `ShellCommand` template executed with the tool's arguments substituted.
16#[derive(Debug, Clone, Serialize, Deserialize)]
17pub struct ShellCommand {
18    /// Command template, e.g. `"docker run --rm {image} sh -c \"$TH_COMMAND\""`.
19    pub command: String,
20    /// Timeout in seconds. Default: 30.
21    #[serde(default = "default_timeout")]
22    pub timeout_secs: u64,
23    /// Working directory for the command. If `None`, inherits the current
24    /// directory of the TinyHarness process.
25    #[serde(default, skip_serializing_if = "Option::is_none")]
26    pub cwd: Option<String>,
27}
28
29fn default_timeout() -> u64 {
30    30
31}
32
33impl ShellCommand {
34    /// Shell-escape a value for safe inline substitution into an unquoted
35    /// position in a shell command.
36    ///
37    /// Wraps the value in single quotes and escapes any single quotes within
38    /// it by replacing `'` with `'\''`. This prevents shell metacharacters
39    /// in the value (e.g. from LLM responses) from breaking the command.
40    fn shell_escape(value: &str) -> String {
41        // Replace ' with '\'' and wrap in single quotes.
42        // e.g.  I'll do it  →  'I'\''ll do it'
43        let escaped = value.replace('\'', "'\\''");
44        format!("'{}'", escaped)
45    }
46
47    /// Escape a value for safe substitution inside a double-quoted string in
48    /// a shell command.
49    ///
50    /// Inside double quotes, the special characters are `"`, `\`, `$`, and
51    /// backtick. These are backslash-escaped to prevent expansion or early
52    /// quote termination.
53    fn escape_for_double_quote(value: &str) -> String {
54        value
55            .replace('\\', "\\\\")
56            .replace('"', "\\\"")
57            .replace('$', "\\$")
58            .replace('`', "\\`")
59    }
60
61    /// Render the command template by substituting `{var}` placeholders.
62    ///
63    /// The renderer is **quote-context-aware**: it tracks whether each
64    /// `{var}` placeholder appears inside single quotes, double quotes, or
65    /// unquoted in the template, and applies the appropriate escaping:
66    ///
67    /// | Context | Strategy |
68    /// |---------|----------|
69    /// | Unquoted | Wrap in single quotes (`shell_escape`) |
70    /// | Inside `"..."` | Escape `"`, `\`, `$`, `` ` `` for double-quote context |
71    /// | Inside `'...'` | Close the quote, insert `shell_escape`d value, reopen |
72    ///
73    /// This prevents broken quoting when the template already wraps a
74    /// placeholder in quotes, e.g. `echo "{user_input}"` or `echo '{tool}'`.
75    ///
76    /// Missing variables (not present in `vars`) are left as-is — the
77    /// `{placeholder}` appears literally in the rendered command.
78    pub fn render(&self, vars: &HashMap<String, String>) -> String {
79        let chars: Vec<char> = self.command.chars().collect();
80        let mut result = String::new();
81        let mut i = 0;
82        let mut in_single = false;
83        let mut in_double = false;
84
85        while i < chars.len() {
86            let c = chars[i];
87
88            if c == '\'' && !in_double {
89                in_single = !in_single;
90                result.push(c);
91                i += 1;
92            } else if c == '"' && !in_single {
93                in_double = !in_double;
94                result.push(c);
95                i += 1;
96            } else if c == '{' {
97                // Try to find a matching `}` and look up the var name.
98                if let Some(end) = chars[i + 1..].iter().position(|&ch| ch == '}') {
99                    let var_name: String = chars[i + 1..i + 1 + end].iter().collect();
100                    if let Some(value) = vars.get(&var_name) {
101                        if in_double {
102                            // Inside double quotes: escape special chars
103                            // for double-quote context.
104                            result.push_str(&Self::escape_for_double_quote(value));
105                        } else if in_single {
106                            // Inside single quotes: close the quote, insert
107                            // the shell-escaped value, then reopen.
108                            // e.g. 'It is {var}' with value=it's →
109                            //   'It is '\''it'\''s''
110                            result.push('\'');
111                            result.push_str(&Self::shell_escape(value));
112                            result.push('\'');
113                        } else {
114                            // Unquoted: wrap in single quotes.
115                            result.push_str(&Self::shell_escape(value));
116                        }
117                        i += end + 2;
118                        continue;
119                    }
120                }
121                // Not a known var or no closing `}` — push literally.
122                result.push(c);
123                i += 1;
124            } else {
125                result.push(c);
126                i += 1;
127            }
128        }
129
130        result
131    }
132
133    /// Execute the command asynchronously.
134    ///
135    /// Returns `Ok(stdout)` on success (exit code 0), or `Err(message)` on
136    /// failure (non-zero exit, timeout, or spawn error).
137    ///
138    /// The `vars` are used for both `{var}` template substitution and as
139    /// `TH_*` environment variables.
140    pub async fn execute(&self, vars: &HashMap<String, String>) -> Result<String, String> {
141        let rendered = self.render(vars);
142
143        let mut cmd = if cfg!(target_os = "windows") {
144            let mut c = tokio::process::Command::new("cmd");
145            c.arg("/C").arg(&rendered);
146            c
147        } else {
148            let mut c = tokio::process::Command::new("sh");
149            c.arg("-c").arg(&rendered);
150            c
151        };
152
153        // Set environment variables
154        for (key, value) in vars {
155            let env_key = format!("TH_{}", key.to_uppercase().replace([' ', '-'], "_"));
156            cmd.env(env_key, value);
157        }
158        // Also set the raw key as an env var for convenience
159        for (key, value) in vars {
160            cmd.env(key, value);
161        }
162
163        if let Some(ref cwd) = self.cwd {
164            cmd.current_dir(cwd);
165        }
166
167        let mut child = cmd
168            .stdout(std::process::Stdio::piped())
169            .stderr(std::process::Stdio::piped())
170            .spawn()
171            .map_err(|e| format!("Failed to spawn command: {}", e))?;
172
173        let timeout = tokio::time::Duration::from_secs(self.timeout_secs);
174        let wait_result = tokio::time::timeout(timeout, child.wait()).await;
175
176        match wait_result {
177            Ok(Ok(status)) => {
178                let stdout = read_pipe(child.stdout.take()).await;
179                let stderr = read_pipe(child.stderr.take()).await;
180
181                if status.success() {
182                    Ok(stdout.trim().to_string())
183                } else {
184                    let mut msg =
185                        format!("Command exited with code {}", status.code().unwrap_or(-1));
186                    if !stderr.is_empty() {
187                        msg.push_str(&format!("\n{}", stderr.trim()));
188                    }
189                    if !stdout.is_empty() {
190                        msg.push_str(&format!("\n{}", stdout.trim()));
191                    }
192                    Err(msg)
193                }
194            }
195            Ok(Err(e)) => {
196                let _ = child.kill().await;
197                let _ = child.wait().await;
198                Err(format!("Failed to wait for command: {}", e))
199            }
200            Err(_) => {
201                let _ = child.kill().await;
202                let _ = child.wait().await;
203                Err(format!(
204                    "Command timed out after {}s: {}",
205                    self.timeout_secs, rendered
206                ))
207            }
208        }
209    }
210}
211
212/// Read a piped stdout/stderr to a string, truncating at 10 KB.
213async fn read_pipe<T: tokio::io::AsyncRead + Unpin>(mut pipe: Option<T>) -> String {
214    if let Some(ref mut r) = pipe.as_mut() {
215        let mut buf = String::new();
216        let _ = r.read_to_string(&mut buf).await;
217        buf
218    } else {
219        String::new()
220    }
221}
222
223/// Execute a shell command for a custom tool, substituting tool arguments.
224///
225/// The tool arguments are passed as a `HashMap<String, String>` (same as
226/// built-in tools).
227pub async fn execute_shell_tool(command: &ShellCommand, args: &HashMap<String, String>) -> String {
228    match command.execute(args).await {
229        Ok(stdout) => {
230            if stdout.is_empty() {
231                "(no output)".to_string()
232            } else {
233                stdout
234            }
235        }
236        Err(e) => format!("Error: {}", e),
237    }
238}
239
240#[cfg(test)]
241mod tests {
242    use super::*;
243
244    #[test]
245    fn test_render_basic_substitution() {
246        let cmd = ShellCommand {
247            command: "echo {name}".to_string(),
248            timeout_secs: 5,
249            cwd: None,
250        };
251        let mut vars = HashMap::new();
252        vars.insert("name".to_string(), "world".to_string());
253        // Values are shell-escaped (wrapped in single quotes)
254        assert_eq!(cmd.render(&vars), "echo 'world'");
255    }
256
257    #[test]
258    fn test_render_multiple_vars() {
259        let cmd = ShellCommand {
260            command: "docker run --rm {image} sh -c {command}".to_string(),
261            timeout_secs: 30,
262            cwd: None,
263        };
264        let mut vars = HashMap::new();
265        vars.insert("image".to_string(), "ubuntu:latest".to_string());
266        vars.insert("command".to_string(), "ls -la".to_string());
267        // Each value is individually shell-escaped
268        assert_eq!(
269            cmd.render(&vars),
270            "docker run --rm 'ubuntu:latest' sh -c 'ls -la'"
271        );
272    }
273
274    #[test]
275    fn test_render_shell_escapes_single_quotes() {
276        let cmd = ShellCommand {
277            command: "echo {text}".to_string(),
278            timeout_secs: 5,
279            cwd: None,
280        };
281        let mut vars = HashMap::new();
282        vars.insert("text".to_string(), "I'll do it".to_string());
283        // Single quotes in the value are escaped: ' -> '\''
284        assert_eq!(cmd.render(&vars), "echo 'I'\\''ll do it'");
285    }
286
287    #[test]
288    fn test_render_shell_escapes_metacharacters() {
289        let cmd = ShellCommand {
290            command: "echo -n {response} | wc -c".to_string(),
291            timeout_secs: 5,
292            cwd: None,
293        };
294        let mut vars = HashMap::new();
295        vars.insert(
296            "response".to_string(),
297            "I'll find all files in `./src` and run $(whoami)".to_string(),
298        );
299        let rendered = cmd.render(&vars);
300        // The value is safely quoted — metacharacters are inert
301        assert_eq!(
302            rendered,
303            "echo -n 'I'\\''ll find all files in `./src` and run $(whoami)' | wc -c"
304        );
305    }
306
307    #[test]
308    fn test_render_inside_double_quotes() {
309        let cmd = ShellCommand {
310            command: "echo \"{text}\"".to_string(),
311            timeout_secs: 5,
312            cwd: None,
313        };
314        let mut vars = HashMap::new();
315        vars.insert("text".to_string(), "He said \"hi\" and $HOME".to_string());
316        // Inside double quotes: escape ", \, $, ` for double-quote context
317        let rendered = cmd.render(&vars);
318        assert_eq!(rendered, "echo \"He said \\\"hi\\\" and \\$HOME\"");
319    }
320
321    #[test]
322    fn test_render_inside_double_quotes_backtick() {
323        let cmd = ShellCommand {
324            command: "echo \"{text}\"".to_string(),
325            timeout_secs: 5,
326            cwd: None,
327        };
328        let mut vars = HashMap::new();
329        vars.insert("text".to_string(), "run `whoami`".to_string());
330        let rendered = cmd.render(&vars);
331        assert_eq!(rendered, "echo \"run \\`whoami\\`\"");
332    }
333
334    #[test]
335    fn test_render_inside_double_quotes_simple() {
336        let cmd = ShellCommand {
337            command: "echo \"{name}\"".to_string(),
338            timeout_secs: 5,
339            cwd: None,
340        };
341        let mut vars = HashMap::new();
342        vars.insert("name".to_string(), "world".to_string());
343        // Simple value inside double quotes — no extra quoting needed
344        let rendered = cmd.render(&vars);
345        assert_eq!(rendered, "echo \"world\"");
346    }
347
348    #[test]
349    fn test_render_inside_single_quotes() {
350        let cmd = ShellCommand {
351            command: "echo '{text}'".to_string(),
352            timeout_secs: 5,
353            cwd: None,
354        };
355        let mut vars = HashMap::new();
356        vars.insert("text".to_string(), "it's here".to_string());
357        let rendered = cmd.render(&vars);
358        assert_eq!(rendered, "echo '''it'\\''s here'''");
359    }
360
361    #[test]
362    fn test_render_inside_single_quotes_simple() {
363        let cmd = ShellCommand {
364            command: "echo '{name}'".to_string(),
365            timeout_secs: 5,
366            cwd: None,
367        };
368        let mut vars = HashMap::new();
369        vars.insert("name".to_string(), "world".to_string());
370        let rendered = cmd.render(&vars);
371        assert_eq!(rendered, "echo '''world'''");
372    }
373
374    #[test]
375    fn test_render_mixed_quotes_multiple_vars() {
376        let cmd = ShellCommand {
377            command: "echo \"{greeting}\" '{name}'".to_string(),
378            timeout_secs: 5,
379            cwd: None,
380        };
381        let mut vars = HashMap::new();
382        vars.insert("greeting".to_string(), "hello $USER".to_string());
383        vars.insert("name".to_string(), "world".to_string());
384        let rendered = cmd.render(&vars);
385        assert_eq!(rendered, "echo \"hello \\$USER\" '''world'''");
386    }
387
388    #[test]
389    fn test_render_nested_brace_not_var() {
390        let cmd = ShellCommand {
391            command: "echo {not_a_var}".to_string(),
392            timeout_secs: 5,
393            cwd: None,
394        };
395        let vars = HashMap::new();
396        // Unknown var stays as literal {not_a_var}
397        assert_eq!(cmd.render(&vars), "echo {not_a_var}");
398    }
399
400    #[test]
401    fn test_render_unclosed_brace() {
402        let cmd = ShellCommand {
403            command: "echo {name".to_string(),
404            timeout_secs: 5,
405            cwd: None,
406        };
407        let mut vars = HashMap::new();
408        vars.insert("name".to_string(), "world".to_string());
409        // No closing } — push { literally
410        assert_eq!(cmd.render(&vars), "echo {name");
411    }
412
413    #[test]
414    fn test_render_missing_var_stays_as_placeholder() {
415        let cmd = ShellCommand {
416            command: "echo {missing}".to_string(),
417            timeout_secs: 5,
418            cwd: None,
419        };
420        let vars = HashMap::new();
421        // Missing vars are left as-is (not replaced with empty string)
422        assert_eq!(cmd.render(&vars), "echo {missing}");
423    }
424
425    #[test]
426    fn test_render_no_vars() {
427        let cmd = ShellCommand {
428            command: "git status".to_string(),
429            timeout_secs: 5,
430            cwd: None,
431        };
432        let vars = HashMap::new();
433        assert_eq!(cmd.render(&vars), "git status");
434    }
435
436    #[test]
437    fn test_default_timeout() {
438        assert_eq!(default_timeout(), 30);
439    }
440
441    #[test]
442    fn test_shell_command_serde() {
443        let json = r#"{"command": "echo hi", "timeout_secs": 10}"#;
444        let cmd: ShellCommand = serde_json::from_str(json).unwrap();
445        assert_eq!(cmd.command, "echo hi");
446        assert_eq!(cmd.timeout_secs, 10);
447        assert!(cmd.cwd.is_none());
448    }
449
450    #[test]
451    fn test_shell_command_serde_default_timeout() {
452        let json = r#"{"command": "echo hi"}"#;
453        let cmd: ShellCommand = serde_json::from_str(json).unwrap();
454        assert_eq!(cmd.timeout_secs, 30);
455    }
456
457    #[test]
458    fn test_shell_command_serde_with_cwd() {
459        let json = r#"{"command": "ls", "timeout_secs": 5, "cwd": "/tmp"}"#;
460        let cmd: ShellCommand = serde_json::from_str(json).unwrap();
461        assert_eq!(cmd.cwd.as_deref(), Some("/tmp"));
462    }
463
464    #[tokio::test]
465    async fn test_execute_success() {
466        let cmd = ShellCommand {
467            command: "echo hello".to_string(),
468            timeout_secs: 5,
469            cwd: None,
470        };
471        let vars = HashMap::new();
472        let result = cmd.execute(&vars).await;
473        assert!(result.is_ok());
474        assert_eq!(result.unwrap(), "hello");
475    }
476
477    #[tokio::test]
478    async fn test_execute_with_substitution() {
479        // On Windows, cmd /C doesn't strip single quotes the way sh does,
480        // so shell-escaped values appear literally in the output.
481        let expected = if cfg!(target_os = "windows") {
482            "'world'"
483        } else {
484            "world"
485        };
486        let cmd = ShellCommand {
487            command: "echo {name}".to_string(),
488            timeout_secs: 5,
489            cwd: None,
490        };
491        let mut vars = HashMap::new();
492        vars.insert("name".to_string(), "world".to_string());
493        let result = cmd.execute(&vars).await;
494        assert!(result.is_ok());
495        assert_eq!(result.unwrap(), expected);
496    }
497
498    #[tokio::test]
499    async fn test_execute_failure() {
500        let cmd = ShellCommand {
501            command: "exit 1".to_string(),
502            timeout_secs: 5,
503            cwd: None,
504        };
505        let vars = HashMap::new();
506        let result = cmd.execute(&vars).await;
507        assert!(result.is_err());
508        assert!(result.unwrap_err().contains("exited with code 1"));
509    }
510
511    #[tokio::test]
512    async fn test_execute_timeout() {
513        // Use a long-running command that works on both platforms.
514        let cmd = ShellCommand {
515            command: (if cfg!(target_os = "windows") {
516                "ping -n 100 127.0.0.1 > NUL"
517            } else {
518                "sleep 100"
519            })
520            .to_string(),
521            timeout_secs: 1,
522            cwd: None,
523        };
524        let vars = HashMap::new();
525        let result = cmd.execute(&vars).await;
526        assert!(result.is_err());
527        assert!(
528            result.unwrap_err().contains("timed out"),
529            "expected 'timed out' in error"
530        );
531    }
532
533    #[tokio::test]
534    async fn test_execute_env_var_available() {
535        let cmd = ShellCommand {
536            command: (if cfg!(target_os = "windows") {
537                "echo %TH_NAME%"
538            } else {
539                "echo $TH_NAME"
540            })
541            .to_string(),
542            timeout_secs: 5,
543            cwd: None,
544        };
545        let mut vars = HashMap::new();
546        vars.insert("name".to_string(), "from_env".to_string());
547        let result = cmd.execute(&vars).await;
548        assert!(result.is_ok());
549        assert_eq!(result.unwrap(), "from_env");
550    }
551
552    #[tokio::test]
553    async fn test_execute_cwd() {
554        let tmp = std::env::temp_dir();
555        let cmd = ShellCommand {
556            command: (if cfg!(target_os = "windows") {
557                "cd"
558            } else {
559                "pwd"
560            })
561            .to_string(),
562            timeout_secs: 5,
563            cwd: Some(tmp.to_string_lossy().to_string()),
564        };
565        let vars = HashMap::new();
566        let result = cmd.execute(&vars).await;
567        assert!(result.is_ok());
568        let expected = std::fs::canonicalize(&tmp)
569            .unwrap_or_else(|_| tmp.clone())
570            .to_string_lossy()
571            .to_string();
572        let actual = result.unwrap();
573        if cfg!(target_os = "windows") {
574            let actual_canon = std::fs::canonicalize(&actual)
575                .or_else(|_| std::path::Path::new(&actual).canonicalize())
576                .map(|p| p.to_string_lossy().to_string())
577                .unwrap_or(actual);
578            let expected_canon = std::fs::canonicalize(&expected)
579                .map(|p| p.to_string_lossy().to_string())
580                .unwrap_or(expected);
581            assert_eq!(actual_canon.to_lowercase(), expected_canon.to_lowercase());
582        } else {
583            assert_eq!(actual, expected);
584        }
585    }
586
587    #[tokio::test]
588    async fn test_execute_shell_tool_success() {
589        let expected = if cfg!(target_os = "windows") {
590            "hello 'world'"
591        } else {
592            "hello world"
593        };
594        let cmd = ShellCommand {
595            command: "echo hello {name}".to_string(),
596            timeout_secs: 5,
597            cwd: None,
598        };
599        let mut args = HashMap::new();
600        args.insert("name".to_string(), "world".to_string());
601        let result = execute_shell_tool(&cmd, &args).await;
602        assert_eq!(result, expected);
603    }
604
605    #[tokio::test]
606    async fn test_execute_shell_tool_error() {
607        let cmd = ShellCommand {
608            command: "exit 42".to_string(),
609            timeout_secs: 5,
610            cwd: None,
611        };
612        let args = HashMap::new();
613        let result = execute_shell_tool(&cmd, &args).await;
614        assert!(result.starts_with("Error:"));
615    }
616
617    #[tokio::test]
618    async fn test_execute_shell_tool_empty_output() {
619        let cmd = ShellCommand {
620            command: "true".to_string(),
621            timeout_secs: 5,
622            cwd: None,
623        };
624        let args = HashMap::new();
625        let result = execute_shell_tool(&cmd, &args).await;
626        assert_eq!(result, "(no output)");
627    }
628
629    #[tokio::test]
630    async fn test_execute_double_quoted_var_with_special_chars() {
631        let cmd = ShellCommand {
632            command: "echo \"{text}\"".to_string(),
633            timeout_secs: 5,
634            cwd: None,
635        };
636        let mut vars = HashMap::new();
637        vars.insert("text".to_string(), "He said \"hi\" and $FOO".to_string());
638        let result = cmd.execute(&vars).await;
639        assert!(result.is_ok());
640        if cfg!(target_os = "windows") {
641            // cmd /C echoes backslash escapes and $ literally; the exact
642            // output is platform-specific, so only check the command succeeds.
643        } else {
644            assert_eq!(result.unwrap(), "He said \"hi\" and $FOO");
645        }
646    }
647
648    #[tokio::test]
649    async fn test_execute_single_quoted_var_with_single_quote() {
650        let cmd = ShellCommand {
651            command: "echo '{text}'".to_string(),
652            timeout_secs: 5,
653            cwd: None,
654        };
655        let mut vars = HashMap::new();
656        vars.insert("text".to_string(), "it's here".to_string());
657        let result = cmd.execute(&vars).await;
658        assert!(result.is_ok());
659        if cfg!(target_os = "windows") {
660            // cmd /C treats single quotes as literal characters.
661        } else {
662            assert_eq!(result.unwrap(), "it's here");
663        }
664    }
665
666    #[tokio::test]
667    async fn test_execute_unquoted_var_with_single_quote() {
668        let cmd = ShellCommand {
669            command: "echo {text}".to_string(),
670            timeout_secs: 5,
671            cwd: None,
672        };
673        let mut vars = HashMap::new();
674        vars.insert("text".to_string(), "it's here".to_string());
675        let result = cmd.execute(&vars).await;
676        assert!(result.is_ok());
677        if cfg!(target_os = "windows") {
678            // cmd /C treats single quotes as literal characters.
679        } else {
680            assert_eq!(result.unwrap(), "it's here");
681        }
682    }
683}