Class ShellApi

Resolve verb-position aliases on a ParsedCommand, returning the (possibly rewritten) command plus an expansion record when one or more aliases fired.

Operates on classified RawTokens — leverages the tokenizer's existing quoting/escape work rather than manipulating raw text. Pure on its inputs except for reading giver.getAlias.

Behaviors:

• Bypass prefix. A verb starting with \ is stripped of the leading backslash and not subject to alias lookup. \\look produces the literal verb \look (the second `` is taken as part of the verb).
• Positional substitution. $1..$9 and $@ (bare or braced) inside word and long-with-value.value text expand against the user's args. A naked $@ token expands to the full user-arg list as separate tokens; embedded $@ is a space-joined string.
• Consume-vs-append. If any positional ref appeared in the body, user-args were consumed and are NOT appended; otherwise they're appended bash-style.
• Recursion. The expansion's resulting verb is itself subject to alias lookup, with a per-call in-flight Set as cycle guard and a hard depth ceiling (16). Cycles terminate silently; depth-cap fires a soft MudlogApi.warn when the giver is a Sensor.
• Source reconstruction. The returned ParsedCommand carries a synthesized source faithful enough for greedy positionals: append case preserves the user's literal post-verb slice; consume case uses CommandLineApi.format so quoted user-args round-trip with their interior whitespace.

Caller is responsible for gating on MixinApi.isAlias(giver) — this function takes Stuff & Alias directly so the type discipline is at the call site.

Expand $X / ${X} references inside text using giver as the resolution context. $$ is left intact for MQL.

Caller's responsibility to gate (skip when the giver doesn't compose EnvironmentMixin, or when shell.interpolate-vars is off). This keeps the function pure on its inputs — the YAML scope expander, for example, runs unconditionally.

Walk the giver's mixin chain and return the first matching synthetic var entry, or null if no mixin declares it.

Cross-host explicit-override resolution. Returns the user-explicit override for key (no schema-default fallback), or undefined when the host can't carry overrides (non-Environment) OR hasn't set the key. Companion to resolveSetting; chain-resolution consumers use this to distinguish "user set X" from "schema default is X".

Cross-host setting resolution.

Settings declared on a mixin that may be composed by hosts without EnvironmentMixin (notably MobileMixin settings on NPCs) need a single resolution entry point so consumers don't branch on the host type. This walks the schema and falls back to the declared default when the host can't carry overrides.