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
+147 -26
View File
@@ -74,7 +74,7 @@ export function splitCommand(command: string): CommandParts {
}
const i = programIndex(words);
if (i >= words.length) return { tool: null, program: command.trim() };
const program = basename(words[i]);
const program = basename(words[i].text);
return { tool: BY_PROGRAM[program.toLowerCase()] ?? null, program };
}
@@ -86,20 +86,41 @@ function legacyFirstWord(command: string): string {
return first === undefined ? command.trim() : basename(first);
}
/** One token from {@link tokenize}: its dequoted text, and — when a
* literal, unquoted/unescaped `=` occurred in the source before any
* quoting or escaping ever touched this word — the index 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. */
interface Word {
text: string;
plainEq: number | null;
}
/** `FOO=bar`, the shell's own prefix for one command's environment —
* recognised only when the `=` came from plain, unquoted/unescaped source
* text (#199). */
function isEnvAssignment(word: Word): boolean {
if (word.plainEq === null) return false;
return /^[A-Za-z_][A-Za-z0-9_]*$/.test(word.text.slice(0, word.plainEq));
}
/** Walk `words` past leading `FOO=bar` assignments and known wrapper forms
* (interleaved in any order/count) to the index of the actual program. */
function programIndex(words: string[]): number {
function programIndex(words: Word[]): number {
const texts = words.map((w) => w.text);
let i = 0;
while (i < words.length) {
const word = words[i];
if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word)) {
if (isEnvAssignment(words[i])) {
i += 1;
continue;
}
const wrapper = basename(word).toLowerCase();
const wrapper = basename(texts[i]).toLowerCase();
const resolver = WRAPPER_RESOLVERS[wrapper];
if (!resolver) break;
const next = resolver(words, i);
const next = resolver(texts, i);
// Not a form of the wrapper we recognise (an unknown option, or — for
// `pnpm`/`yarn`/`bun` — no `dlx`/`x` subcommand behind it): the wrapper
// word itself is the program, not a launcher.
@@ -118,24 +139,32 @@ function basename(word: string): string {
* `\` quoting/escaping — POSIX quote *removal*, not evaluation) and return
* `null` 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. */
function tokenize(command: string): string[] | null {
const words: 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). */
function tokenize(command: string): Word[] | null {
const words: Word[] = [];
let current = "";
let hasCurrent = false;
let plainEq: number | null = null;
let i = 0;
const n = command.length;
while (i < n) {
const c = command[i];
if (c === " " || c === "\t" || c === "\n" || c === "\r") {
if (c === " " || c === "\t" || c === "\r") {
if (hasCurrent) {
words.push(current);
words.push({ text: current, plainEq });
current = "";
hasCurrent = false;
plainEq = null;
}
i += 1;
} else if (c === "\n") {
return null;
} else if ("|&;<>()`".includes(c)) {
return null;
} else if (c === "$" && command[i + 1] === "(") {
@@ -160,6 +189,10 @@ function tokenize(command: string): string[] | null {
if (c2 === "\\") {
const escaped = command[i + 1];
if (escaped === undefined) return null; // trailing backslash
if (escaped === "\n") {
i += 2; // line continuation, removed entirely
continue;
}
current += '"\\$`'.includes(escaped) ? escaped : "\\" + escaped;
i += 2;
} else {
@@ -170,16 +203,23 @@ function tokenize(command: string): string[] | null {
} else if (c === "\\") {
const escaped = command[i + 1];
if (escaped === undefined) return null; // trailing backslash
if (escaped === "\n") {
i += 2; // line continuation, removed entirely
continue;
}
hasCurrent = true;
current += escaped;
i += 2;
} else {
hasCurrent = true;
if (c === "=" && plainEq === null) {
plainEq = current.length;
}
current += c;
i += 1;
}
}
if (hasCurrent) words.push(current);
if (hasCurrent) words.push({ text: current, plainEq });
return words;
}
@@ -191,6 +231,33 @@ function tokenize(command: string): string[] | null {
interface OptionTable {
flags: Set<string>;
valued: Set<string>;
/** 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. */
bundlesShortOptions: boolean;
}
/** `-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). */
function matchesShortCluster(opts: OptionTable, word: string): boolean {
let idx = 1;
while (idx < word.length) {
const short = "-" + word[idx];
if (opts.flags.has(short)) {
idx += 1;
continue;
}
if (opts.valued.has(short)) {
return idx + 1 < word.length;
}
return false;
}
return true;
}
/** Consume `opts`'s options starting at `words[i]`, returning the index just
@@ -220,15 +287,25 @@ function consumeOptions(opts: OptionTable, words: string[], i: number): number |
i += 2;
continue;
}
if (
opts.bundlesShortOptions &&
!word.startsWith("--") &&
word.length > 2 &&
matchesShortCluster(opts, word)
) {
i += 1;
continue;
}
return null;
}
}
const NO_OPTIONS: OptionTable = { flags: new Set(), valued: new Set() };
const NO_OPTIONS: OptionTable = { flags: new Set(), valued: new Set(), bundlesShortOptions: false };
const ENV_OPTS: OptionTable = {
flags: new Set(["-i", "--ignore-environment", "-0", "--null"]),
valued: new Set(["-u", "--unset", "-C", "--chdir", "-S", "--split-string"]),
flags: new Set(["-i", "--ignore-environment", "-0", "--null", "-v", "--debug"]),
valued: new Set(["-u", "--unset", "-C", "--chdir"]),
bundlesShortOptions: true,
};
const SUDO_OPTS: OptionTable = {
@@ -253,47 +330,91 @@ const SUDO_OPTS: OptionTable = {
"--stdin",
]),
valued: new Set(["-u", "--user", "-g", "--group"]),
bundlesShortOptions: 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 = {
flags: new Set(["-p", "-v", "-V"]),
flags: new Set(["-p"]),
valued: new Set(),
bundlesShortOptions: 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 = {
flags: new Set(["-p", "--portability", "-v", "--verbose", "-a", "--append", "-q", "--quiet"]),
valued: new Set(["-o", "--output", "-f", "--format"]),
flags: new Set(["-p"]),
valued: new Set(),
bundlesShortOptions: 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 = {
flags: new Set(["-y", "--yes", "--no", "-q", "--quiet", "--ignore-existing"]),
valued: new Set(["-p", "--package", "-c", "--call", "--shell"]),
valued: new Set(["-p", "--package", "--shell"]),
bundlesShortOptions: false,
};
const PNPM_OPTS: OptionTable = {
flags: new Set(["--silent", "-s", "--stream", "--aggregate-output", "--no-progress"]),
valued: new Set(["-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: new Set(["-C", "--dir", "--filter", "--package"]),
bundlesShortOptions: false,
};
const YARN_OPTS: OptionTable = {
flags: new Set(["--silent", "-s", "--no-progress", "--non-interactive"]),
valued: new Set(["--cwd"]),
bundlesShortOptions: 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 = {
flags: new Set(),
valued: new Set(["--package"]),
bundlesShortOptions: 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 = {
flags: new Set(["--bun"]),
valued: new Set(),
bundlesShortOptions: false,
};
/** `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. */
function resolveDlx(opts: OptionTable, words: string[], i: number): number | null {
const j = consumeOptions(opts, words, i + 1);
if (j === null) return null;
return words[j] === "dlx" ? j + 1 : null;
if (words[j] !== "dlx") return null;
return consumeOptions(DLX_TRAILING_OPTS, 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. */
function resolveBun(words: string[], i: number): number | null {
return words[i + 1] === "x" ? i + 2 : null;
if (words[i + 1] !== "x") return null;
return consumeOptions(BUN_X_OPTS, words, i + 2);
}
/** A resolver for one wrapper form: given the tokenized command and the
@@ -312,7 +433,7 @@ const WRAPPER_RESOLVERS: Record<string, WrapperResolver> = {
pnpm: (words, i) => resolveDlx(PNPM_OPTS, words, i),
yarn: (words, i) => resolveDlx(YARN_OPTS, words, i),
bun: resolveBun,
bunx: (_words, i) => i + 1,
bunx: (words, i) => consumeOptions(BUN_X_OPTS, words, i + 1),
uvx: (_words, i) => i + 1,
};