fix(maestro): close command-resolution gaps from #199 review

Fixes six issues in the shared command resolver (Rust display.rs and
its TS mirror toolIcon.ts), all locked in by shared fixture cases:

- An unescaped newline now ends resolution like `;` does, instead of
  being folded in as whitespace; a backslash-newline is a line
  continuation, removed entirely rather than embedded or splitting
  the word.
- Assignment recognition (`FOO=bar`) now requires the `=` to come from
  plain, unquoted/unescaped source text. `"FOO=1"` and `FOO\=1` are
  executable words named `FOO=1`, not assignments — quote removal was
  losing that provenance.
- `command -v`/`-V` (lookup only, no execution), `env -S` (embeds a
  command string) and `npx -c`/`--call` (same) no longer resolve
  through to a program they don't actually run. Restricted bash
  `time`'s options to `-p`, the only flag the keyword itself parses
  (`-o` etc. belong to external GNU time) — this corrects a
  previously-wrong fixture case.
- `env`, `sudo` and `command`'s options may now bundle (`env -iv`,
  `sudo -nE`) or take an attached value (`sudo -uroot`), the way real
  getopt-based tools do, with missing-operand forms safely rejected.
- pnpm/yarn `dlx` and `bun x`/`bunx` now consume their own trailing
  options (`--package foo`/`--package=foo`, `--bun`) before the
  executable, matching each tool's documented CLI syntax.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Miguel Palhas
2026-09-05 13:51:43 +01:00
co-authored by Claude Sonnet 5
parent 370edfa763
commit 0af91296df
3 changed files with 391 additions and 76 deletions
+219 -49
View File
@@ -239,14 +239,14 @@ struct Resolution {
/// when [`tokenize`] can't safely make sense of the line at all.
fn resolve(command: &str) -> Option<Resolution> {
let words = tokenize(command)?;
let refs: Vec<&str> = words.iter().map(String::as_str).collect();
let refs: Vec<&str> = words.iter().map(|w| w.text.as_str()).collect();
let mut i = 0;
while let Some(&word) = refs.get(i) {
while let Some(word) = words.get(i) {
if is_env_assignment(word) {
i += 1;
continue;
}
let wrapper = basename(word).to_lowercase();
let wrapper = basename(&word.text).to_lowercase();
let Some(resolver) = wrapper_resolver(&wrapper) else {
break;
};
@@ -259,7 +259,7 @@ fn resolve(command: &str) -> Option<Resolution> {
}
}
Some(Resolution {
words,
words: words.into_iter().map(|w| w.text).collect(),
program_index: i,
})
}
@@ -274,26 +274,49 @@ fn legacy_first_word(command: &str) -> String {
}
}
/// One token from [`tokenize`]: its dequoted text, and — when a literal,
/// unquoted/unescaped `=` occurred in the source before any quoting or
/// escaping ever touched this word — the byte length of the name preceding
/// it. Only a *plain* `=` counts as an assignment's: quoting or escaping it
/// (`"FOO=1"`, `FOO\=1`) makes the word an executable command named
/// `FOO=1`, not an assignment (#199) — quoting elsewhere in the word (a
/// value, or even part of the name, as in `FO"O"=1`) doesn't disqualify it,
/// matching a real shell's own assignment-word grammar.
#[derive(Debug, Clone, PartialEq, Eq)]
struct Word {
text: String,
plain_eq: Option<usize>,
}
/// Word-split `command` the way a shell would (honouring `'…'`, `"…"` and
/// `\` quoting/escaping — POSIX quote *removal*, not evaluation) and return
/// `None` the moment it needs real shell grammar this resolver doesn't
/// attempt: a pipeline/list operator (`|`, `&`, `;`, `<`, `>`), a subshell or
/// substitution (`(`, `)`, `` ` ``, `$(`), or an unterminated quote/escape.
/// Never expands `$var`/`` `cmd` ``/`$(cmd)` — a bare `$` is kept literal.
fn tokenize(command: &str) -> Option<Vec<String>> {
/// substitution (`(`, `)`, `` ` ``, `$(`), an unescaped newline (a command
/// separator, like `;` — #199), or an unterminated quote/escape. Never
/// expands `$var`/`` `cmd` ``/`$(cmd)` — a bare `$` is kept literal. A
/// backslash immediately before a newline, quoted or not, is a line
/// continuation: removed entirely rather than embedding the newline or
/// ending the word (#199).
fn tokenize(command: &str) -> Option<Vec<Word>> {
let mut words = Vec::new();
let mut current = String::new();
let mut has_current = false;
let mut plain_eq: Option<usize> = None;
let mut chars = command.chars().peekable();
while let Some(c) = chars.next() {
match c {
' ' | '\t' | '\n' | '\r' => {
' ' | '\t' | '\r' => {
if has_current {
words.push(std::mem::take(&mut current));
words.push(Word {
text: std::mem::take(&mut current),
plain_eq: plain_eq.take(),
});
has_current = false;
}
}
'\n' => return None,
'|' | '&' | ';' | '<' | '>' | '(' | ')' | '`' => return None,
'$' if chars.peek() == Some(&'(') => return None,
'\'' => {
@@ -313,6 +336,7 @@ fn tokenize(command: &str) -> Option<Vec<String>> {
Some('"') => break,
Some('\\') => match chars.next() {
Some(c2 @ ('"' | '\\' | '$' | '`')) => current.push(c2),
Some('\n') => {} // line continuation, removed entirely
Some(c2) => {
current.push('\\');
current.push(c2);
@@ -324,18 +348,28 @@ fn tokenize(command: &str) -> Option<Vec<String>> {
}
}
}
'\\' => {
has_current = true;
current.push(chars.next()?); // None: trailing backslash
}
'\\' => match chars.next() {
Some('\n') => {} // line continuation, removed entirely
Some(c2) => {
has_current = true;
current.push(c2);
}
None => return None, // trailing backslash
},
other => {
has_current = true;
if other == '=' && plain_eq.is_none() {
plain_eq = Some(current.len());
}
current.push(other);
}
}
}
if has_current {
words.push(current);
words.push(Word {
text: current,
plain_eq,
});
}
Some(words)
}
@@ -348,6 +382,12 @@ fn tokenize(command: &str) -> Option<Vec<String>> {
struct OptionTable {
flags: &'static [&'static str],
valued: &'static [&'static str],
/// Whether this wrapper's short options may be combined (`-iv`) or take
/// an attached value (`-uroot`), the way real getopt-based tools do
/// (#199). JS-toolchain wrappers (`npx`, `pnpm`, `yarn`, bun's `x`/
/// `dlx`) don't get this — guessing at bundling they don't actually
/// support would resolve through options they'd reject outright.
bundles_short_options: bool,
}
impl OptionTable {
@@ -383,19 +423,64 @@ impl OptionTable {
i += 2;
continue;
}
if self.bundles_short_options
&& !word.starts_with("--")
&& word.len() > 2
&& self.matches_short_cluster(word)
{
i += 1;
continue;
}
return None;
}
}
/// `-iv` (bundled boolean short flags) or `-uroot` (a valued short
/// option with its value attached) — getopt's traditional short-option
/// forms. `false` the moment a character isn't a short option this
/// table knows, or a valued one ends the word with no attached value
/// left to be its operand (#199: rejected rather than guessed to come
/// from the next word instead).
fn matches_short_cluster(&self, word: &str) -> bool {
if !word.is_ascii() {
return false;
}
let bytes = word.as_bytes();
let mut buf = [b'-', 0];
let mut idx = 1;
while idx < bytes.len() {
buf[1] = bytes[idx];
let short = std::str::from_utf8(&buf).expect("ascii buffer");
if self.flags.contains(&short) {
idx += 1;
continue;
}
if self.valued.contains(&short) {
return idx + 1 < bytes.len();
}
return false;
}
true
}
}
const NO_OPTIONS: OptionTable = OptionTable {
flags: &[],
valued: &[],
bundles_short_options: false,
};
const ENV_OPTS: OptionTable = OptionTable {
flags: &["-i", "--ignore-environment", "-0", "--null"],
valued: &["-u", "--unset", "-C", "--chdir", "-S", "--split-string"],
flags: &[
"-i",
"--ignore-environment",
"-0",
"--null",
"-v",
"--debug",
],
valued: &["-u", "--unset", "-C", "--chdir"],
bundles_short_options: true,
};
const SUDO_OPTS: OptionTable = OptionTable {
@@ -420,30 +505,38 @@ const SUDO_OPTS: OptionTable = OptionTable {
"--stdin",
],
valued: &["-u", "--user", "-g", "--group"],
bundles_short_options: true,
};
/// `-v`/`-V` only print what would run — they never execute it — so
/// resolving through them would claim a program runs that `command` never
/// launches (#199). Only `-p`, which still executes normally, is safe to
/// look through.
const COMMAND_BUILTIN_OPTS: OptionTable = OptionTable {
flags: &["-p", "-v", "-V"],
flags: &["-p"],
valued: &[],
bundles_short_options: true,
};
/// The bash *keyword* `time` only ever parses `-p` (POSIX output format);
/// `-o`/`-v`/`-a`/`-f`/`--verbose`/... belong to the external GNU
/// `/usr/bin/time`, a different program a bare `time` word doesn't
/// necessarily name. Assuming them here would be guessing which `time`
/// resolves (#199).
const TIME_OPTS: OptionTable = OptionTable {
flags: &[
"-p",
"--portability",
"-v",
"--verbose",
"-a",
"--append",
"-q",
"--quiet",
],
valued: &["-o", "--output", "-f", "--format"],
flags: &["-p"],
valued: &[],
bundles_short_options: true,
};
/// `-c`/`--call` embeds a whole shell command string rather than naming the
/// program positionally — resolving past it would mean guessing at a
/// program buried inside that string, so it's left unrecognised and
/// resolution stops at `npx` (#199).
const NPX_OPTS: OptionTable = OptionTable {
flags: &["-y", "--yes", "--no", "-q", "--quiet", "--ignore-existing"],
valued: &["-p", "--package", "-c", "--call", "--shell"],
valued: &["-p", "--package", "--shell"],
bundles_short_options: false,
};
const PNPM_OPTS: OptionTable = OptionTable {
@@ -454,12 +547,34 @@ const PNPM_OPTS: OptionTable = OptionTable {
"--aggregate-output",
"--no-progress",
],
valued: &["-C", "--dir", "--filter"],
// `--package`/`--package=value` is documented in this pre-`dlx`
// position (`pnpm --package=x dlx y`), alongside the identical flag
// `dlx` itself also accepts (`DLX_TRAILING_OPTS`).
valued: &["-C", "--dir", "--filter", "--package"],
bundles_short_options: false,
};
const YARN_OPTS: OptionTable = OptionTable {
flags: &["--silent", "-s", "--no-progress", "--non-interactive"],
valued: &["--cwd"],
bundles_short_options: false,
};
/// `--package`/`--package=value` right after `dlx`: both pnpm's and yarn's
/// `dlx` document it there, to run a binary whose name differs from the
/// package that provides it (#199).
const DLX_TRAILING_OPTS: OptionTable = OptionTable {
flags: &[],
valued: &["--package"],
bundles_short_options: false,
};
/// `--bun`, forcing bun's own runtime instead of Node — bun's docs place it
/// right after the `x`/`bunx` trigger, before the executable (#199).
const BUN_X_OPTS: OptionTable = OptionTable {
flags: &["--bun"],
valued: &[],
bundles_short_options: false,
};
/// A resolver for one wrapper form: given the tokenized command and the
@@ -479,38 +594,51 @@ fn wrapper_resolver(name: &str) -> Option<WrapperResolver> {
"pnpm" => Some(|words, i| resolve_dlx(&PNPM_OPTS, words, i)),
"yarn" => Some(|words, i| resolve_dlx(&YARN_OPTS, words, i)),
"bun" => Some(resolve_bun),
"bunx" | "uvx" => Some(|_words, i| Some(i + 1)),
"bunx" => Some(|words, i| BUN_X_OPTS.consume(words, i + 1)),
"uvx" => Some(|_words, i| Some(i + 1)),
_ => None,
}
}
/// `pnpm`/`yarn` only look through to the package behind an explicit `dlx`
/// — without it, the next word is a `package.json` script name, not a
/// package to run (#199: `pnpm claude` is not `pnpm dlx claude`).
/// package to run (#199: `pnpm claude` is not `pnpm dlx claude`). `dlx`
/// itself takes options too (`DLX_TRAILING_OPTS`), consumed before the
/// executable.
fn resolve_dlx(opts: &OptionTable, words: &[&str], i: usize) -> Option<usize> {
let j = opts.consume(words, i + 1)?;
(words.get(j) == Some(&"dlx")).then_some(j + 1)
if words.get(j) != Some(&"dlx") {
return None;
}
DLX_TRAILING_OPTS.consume(words, j + 1)
}
/// `bun x <pkg>` is bun's `dlx`/`npx` equivalent; `bun run <script>` is not
/// (the same package-script ambiguity as bare `pnpm`/`yarn`), so only an `x`
/// subcommand is looked through.
/// subcommand is looked through. `--bun` (`BUN_X_OPTS`) may follow it before
/// the executable.
fn resolve_bun(words: &[&str], i: usize) -> Option<usize> {
(words.get(i + 1) == Some(&"x")).then_some(i + 2)
if words.get(i + 1) != Some(&"x") {
return None;
}
BUN_X_OPTS.consume(words, i + 2)
}
/// `FOO=bar`, the shell's own prefix for one command's environment.
fn is_env_assignment(word: &str) -> bool {
let mut chars = word.chars();
/// `FOO=bar`, the shell's own prefix for one command's environment —
/// recognised only when the `=` came from plain, unquoted/unescaped source
/// text (#199): `"FOO=1"` and `FOO\=1` name a program called `FOO=1`, not
/// an assignment.
fn is_env_assignment(word: &Word) -> bool {
let Some(eq) = word.plain_eq else {
return false;
};
let name = &word.text[..eq];
let mut chars = name.chars();
match chars.next() {
Some(c) if c.is_ascii_alphabetic() || c == '_' => {}
_ => return false,
}
let rest: String = chars.collect();
match rest.split_once('=') {
Some((name, _)) => name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_'),
None => false,
}
chars.all(|c| c.is_ascii_alphanumeric() || c == '_')
}
fn basename(word: &str) -> &str {
@@ -795,32 +923,52 @@ mod tests {
}
}
fn word(text: &str) -> Word {
Word {
text: text.into(),
plain_eq: None,
}
}
/// Shell-aware tokenization (#199): quoting/escaping is honoured, never
/// evaluated — no `$var`/`` `cmd` ``/`$(cmd)` expansion is attempted.
#[test]
fn tokenize_handles_quotes_and_escapes_without_expanding_anything() {
assert_eq!(
tokenize("claude --resume"),
Some(vec!["claude".into(), "--resume".into()])
Some(vec![word("claude"), word("--resume")])
);
assert_eq!(
tokenize("\"/opt/my agent/claude\" --resume"),
Some(vec!["/opt/my agent/claude".into(), "--resume".into()])
Some(vec![word("/opt/my agent/claude"), word("--resume")])
);
assert_eq!(
tokenize("FOO=\"bar baz\" claude"),
Some(vec!["FOO=bar baz".into(), "claude".into()])
Some(vec![
Word {
text: "FOO=bar baz".into(),
plain_eq: Some(3),
},
word("claude"),
])
);
assert_eq!(
tokenize("claude --name=$HOME"),
Some(vec!["claude".into(), "--name=$HOME".into()]),
Some(vec![
word("claude"),
Word {
text: "--name=$HOME".into(),
plain_eq: Some(6),
},
]),
"a bare $ is kept literal, never expanded"
);
}
/// Real shell grammar this resolver doesn't attempt — pipelines, list
/// operators, subshells/substitution, an unterminated quote — is
/// rejected outright rather than guessed through (#199).
/// operators, subshells/substitution, an unescaped newline, an
/// unterminated quote — is rejected outright rather than guessed
/// through (#199).
#[test]
fn tokenize_rejects_ambiguous_shell_grammar() {
for command in [
@@ -831,8 +979,30 @@ mod tests {
"claude \"unterminated",
"claude 'unterminated",
"claude \\",
"claude\nclaude-code", // an unescaped newline separates commands, like `;`
] {
assert_eq!(tokenize(command), None, "{command:?}");
}
}
/// A backslash immediately before a newline is a line continuation:
/// removed entirely, joining what it split rather than embedding a
/// literal newline or ending the command (#199).
#[test]
fn tokenize_treats_backslash_newline_as_a_continuation() {
assert_eq!(
tokenize("clau\\\nde --resume"),
Some(vec![word("claude"), word("--resume")])
);
}
/// Only a plain, unquoted/unescaped `=` marks an assignment boundary —
/// quoting or escaping the `=` itself disqualifies the word, even
/// though the dequoted text looks identical (#199).
#[test]
fn tokenize_only_marks_plain_unquoted_equals_signs_as_assignments() {
assert_eq!(tokenize("FOO=1 claude").unwrap()[0].plain_eq, Some(3));
assert_eq!(tokenize("\"FOO=1\" claude").unwrap()[0].plain_eq, None);
assert_eq!(tokenize("FOO\\=1 claude").unwrap()[0].plain_eq, None);
}
}