chore: import upstream snapshot with attribution

python/tests/workspace/executor/builtins/test_condition.py

@@ -0,0 +1,85 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import pytest
+
+from mirage import MountMode, RAMResource, Workspace
+
+
+async def _workspace() -> Workspace:
+    ws = Workspace({"/": RAMResource()}, mode=MountMode.WRITE)
+    await ws.execute("mkdir -p /data/sub")
+    await ws.execute("tee /data/plain.txt > /dev/null", stdin=b"y\n")
+    await ws.execute("cd /data")
+    return ws
+
+
+async def _rc(ws: Workspace, cmd: str) -> int:
+    io = await ws.execute(cmd)
+    return io.exit_code
+
+
+@pytest.mark.asyncio
+async def test_f_relative_resolves_against_cwd():
+    ws = await _workspace()
+    assert await _rc(ws, "test -f plain.txt") == 0
+
+
+@pytest.mark.asyncio
+async def test_f_relative_missing():
+    ws = await _workspace()
+    assert await _rc(ws, "test -f missing.txt") == 1
+
+
+@pytest.mark.asyncio
+async def test_f_relative_with_dotdot():
+    ws = await _workspace()
+    await ws.execute("cd /data/sub")
+    assert await _rc(ws, "test -f ../plain.txt") == 0
+
+
+@pytest.mark.asyncio
+async def test_d_relative_resolves_against_cwd():
+    ws = await _workspace()
+    assert await _rc(ws, "test -d sub") == 0
+
+
+@pytest.mark.asyncio
+async def test_d_relative_missing():
+    ws = await _workspace()
+    assert await _rc(ws, "test -d nosuch") == 1
+
+
+@pytest.mark.asyncio
+async def test_f_absolute_unchanged():
+    ws = await _workspace()
+    assert await _rc(ws, "test -f /data/plain.txt") == 0
+
+
+@pytest.mark.asyncio
+async def test_f_empty_operand_false():
+    ws = await _workspace()
+    assert await _rc(ws, 'test -f ""') == 1
+
+
+@pytest.mark.asyncio
+async def test_bracket_form_relative():
+    ws = await _workspace()
+    assert await _rc(ws, "[ -f plain.txt ]") == 0
+
+
+@pytest.mark.asyncio
+async def test_negation_relative():
+    ws = await _workspace()
+    assert await _rc(ws, "test ! -f missing.txt") == 0

python/tests/workspace/executor/builtins/test_script.py

@@ -0,0 +1,55 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import time
+
+import pytest
+
+from mirage.workspace.executor.builtins.script import handle_sleep
+
+
+@pytest.mark.asyncio
+async def test_sleep_missing_operand_exits_1():
+    _, io, node = await handle_sleep([])
+    assert io.exit_code == 1
+    assert io.stderr == b"sleep: missing operand\n"
+    assert node.exit_code == 1
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "raw",
+    ["abc", "-1", "inf", "Infinity", "nan", "NaN", "0x10", "1_0", "1e309", ""])
+async def test_sleep_invalid_interval_exits_1(raw):
+    _, io, node = await handle_sleep([raw])
+    assert io.exit_code == 1
+    assert io.stderr == f"sleep: invalid time interval '{raw}'\n".encode()
+    assert node.exit_code == 1
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("raw", ["0", "0.", ".01", "+0.01", "1e-3"])
+async def test_sleep_valid_interval_exits_0(raw):
+    _, io, node = await handle_sleep([raw])
+    assert io.exit_code == 0
+    assert not io.stderr
+    assert node.exit_code == 0
+
+
+@pytest.mark.asyncio
+async def test_sleep_zero_returns_promptly():
+    start = time.monotonic()
+    _, io, _ = await handle_sleep(["0"])
+    assert io.exit_code == 0
+    assert time.monotonic() - start < 0.05

python/tests/workspace/executor/builtins/test_text.py

@@ -0,0 +1,56 @@
+import pytest
+
+from mirage.workspace.executor.builtins.text import handle_echo
+
+
+async def echo_bytes(args: list[str]) -> bytes:
+    out, io, _ = await handle_echo(args)
+    assert io.exit_code == 0
+    assert isinstance(out, bytes)
+    return out
+
+
+@pytest.mark.asyncio
+async def test_plain_words_join_with_newline():
+    assert await echo_bytes(["hi", "there"]) == b"hi there\n"
+
+
+@pytest.mark.asyncio
+async def test_leading_n_suppresses_newline():
+    assert await echo_bytes(["-n", "hi"]) == b"hi"
+
+
+@pytest.mark.asyncio
+async def test_trailing_n_prints_literally():
+    assert await echo_bytes(["hi", "-n"]) == b"hi -n\n"
+
+
+@pytest.mark.asyncio
+async def test_cluster_ne():
+    assert await echo_bytes(["-ne", "a\\tb"]) == b"a\tb"
+
+
+@pytest.mark.asyncio
+async def test_capital_e_disables_escapes():
+    assert await echo_bytes(["-e", "-E", "a\\tb"]) == b"a\\tb\n"
+
+
+@pytest.mark.asyncio
+async def test_last_of_e_and_E_wins_within_cluster():
+    assert await echo_bytes(["-eE", "a\\tb"]) == b"a\\tb\n"
+    assert await echo_bytes(["-Ee", "a\\tb"]) == b"a\tb\n"
+
+
+@pytest.mark.asyncio
+async def test_unknown_char_makes_word_literal():
+    assert await echo_bytes(["-nq", "hi"]) == b"-nq hi\n"
+
+
+@pytest.mark.asyncio
+async def test_option_after_operand_is_literal():
+    assert await echo_bytes(["hi", "-e", "a\\tb"]) == b"hi -e a\\tb\n"
+
+
+@pytest.mark.asyncio
+async def test_lone_dash_is_literal():
+    assert await echo_bytes(["-"]) == b"-\n"

python/tests/workspace/executor/builtins/test_timeout.py

@@ -0,0 +1,99 @@
+import asyncio
+
+import pytest
+
+from mirage.io import IOResult
+from mirage.io.stream import materialize
+from mirage.workspace.executor.builtins.timeout import (handle_timeout,
+                                                        parse_duration)
+from mirage.workspace.session.session import Session
+
+
+class FakeShell:
+
+    def __init__(self, delay: float = 0.0, exit_code: int = 0):
+        self.lines: list[str] = []
+        self.delay = delay
+        self.exit_code = exit_code
+
+    async def __call__(self, line: str, session_id: str) -> IOResult:
+        self.lines.append(line)
+        if self.delay:
+            await asyncio.sleep(self.delay)
+        return IOResult(stdout=b"done\n", exit_code=self.exit_code)
+
+
+def make_session() -> Session:
+    return Session(session_id="s1")
+
+
+def test_parse_duration_units():
+    assert parse_duration("1") == 1.0
+    assert parse_duration("0.5") == 0.5
+    assert parse_duration("2s") == 2.0
+    assert parse_duration("2m") == 120.0
+    assert parse_duration("1h") == 3600.0
+    assert parse_duration("1d") == 86400.0
+    assert parse_duration(".5") == 0.5
+
+
+def test_parse_duration_rejects_garbage():
+    assert parse_duration("xx") is None
+    assert parse_duration("-1") is None
+    assert parse_duration("1x") is None
+    assert parse_duration("") is None
+
+
+@pytest.mark.asyncio
+async def test_command_finishing_in_time_passes_through():
+    shell = FakeShell(exit_code=3)
+    stdout, io, _ = await handle_timeout(shell, ["5", "wc", "-l"],
+                                         make_session())
+    assert shell.lines == ["wc -l"]
+    assert io.exit_code == 3
+    assert stdout == b"done\n"
+
+
+@pytest.mark.asyncio
+async def test_overrun_exits_124():
+    shell = FakeShell(delay=1.0)
+    _, io, node = await handle_timeout(shell, ["0.05", "sleep", "1"],
+                                       make_session())
+    assert io.exit_code == 124
+    assert node.exit_code == 124
+
+
+@pytest.mark.asyncio
+async def test_invalid_duration_exits_125():
+    shell = FakeShell()
+    _, io, _ = await handle_timeout(shell, ["xx", "sleep", "1"],
+                                    make_session())
+    assert io.exit_code == 125
+    assert (await
+            materialize(io.stderr)) == b"timeout: invalid time interval 'xx'\n"
+    assert shell.lines == []
+
+
+@pytest.mark.asyncio
+async def test_missing_operand_exits_125():
+    shell = FakeShell()
+    _, io, _ = await handle_timeout(shell, ["5"], make_session())
+    assert io.exit_code == 125
+    assert await materialize(io.stderr) == b"timeout: missing operand\n"
+
+
+@pytest.mark.asyncio
+async def test_signal_option_rejected():
+    shell = FakeShell()
+    _, io, _ = await handle_timeout(shell, ["-s", "KILL", "1", "sleep", "3"],
+                                    make_session())
+    assert io.exit_code == 125
+    assert (await
+            materialize(io.stderr)) == b"timeout: unsupported option -- '-s'\n"
+
+
+@pytest.mark.asyncio
+async def test_quoting_survives_rejoin():
+    shell = FakeShell()
+    await handle_timeout(shell, ["1", "grep", "a b", "f.txt"], make_session())
+    assert shell.lines == ["grep 'a b' f.txt"]

python/tests/workspace/executor/builtins/test_vars.py

@@ -0,0 +1,76 @@
+import pytest
+
+from mirage.io.stream import materialize
+from mirage.workspace.executor.builtins.vars import (handle_read,
+                                                     handle_return,
+                                                     handle_shift)
+from mirage.workspace.executor.control import ReturnSignal
+from mirage.workspace.session.session import Session
+
+
+def make_session() -> Session:
+    return Session(session_id="s1")
+
+
+@pytest.mark.asyncio
+async def test_shift_non_numeric_errors_like_bash():
+    _, io, _ = await handle_shift(["x"], None, session=make_session())
+    assert io.exit_code == 1
+    assert (await
+            materialize(io.stderr)) == b"shift: x: numeric argument required\n"
+
+
+@pytest.mark.asyncio
+async def test_shift_too_many_arguments():
+    _, io, _ = await handle_shift(["1", "2"], None, session=make_session())
+    assert io.exit_code == 1
+    assert await materialize(io.stderr) == b"shift: too many arguments\n"
+
+
+@pytest.mark.asyncio
+async def test_shift_default_one():
+    session = make_session()
+    session.positional_args = ["a", "b"]
+    _, io, _ = await handle_shift([], None, session=session)
+    assert io.exit_code == 0
+    assert session.positional_args == ["b"]
+
+
+@pytest.mark.asyncio
+async def test_return_non_numeric_raises_2_with_message():
+    with pytest.raises(ReturnSignal) as exc:
+        await handle_return(["x"])
+    assert exc.value.exit_code == 2
+    assert exc.value.stderr == b"return: x: numeric argument required\n"
+
+
+@pytest.mark.asyncio
+async def test_return_numeric():
+    with pytest.raises(ReturnSignal) as exc:
+        await handle_return(["7"])
+    assert exc.value.exit_code == 7
+    assert exc.value.stderr == b""
+
+
+@pytest.mark.asyncio
+async def test_read_invalid_option_exits_2():
+    _, io, _ = await handle_read(["-q", "v"], make_session(), b"line\n")
+    assert io.exit_code == 2
+    assert await materialize(io.stderr) == b"read: -q: invalid option\n"
+
+
+@pytest.mark.asyncio
+async def test_read_dash_r_consumed_not_a_variable():
+    session = make_session()
+    _, io, _ = await handle_read(["-r", "v"], session, b"hello world\n")
+    assert io.exit_code == 0
+    assert session.env["v"] == "hello world"
+    assert "-r" not in session.env
+
+
+@pytest.mark.asyncio
+async def test_read_defaults_to_reply():
+    session = make_session()
+    _, io, _ = await handle_read([], session, b"hi\n")
+    assert io.exit_code == 0
+    assert session.env["REPLY"] == "hi"

python/tests/workspace/executor/builtins/test_xargs.py

@@ -0,0 +1,124 @@
+import pytest
+
+from mirage.io import IOResult
+from mirage.io.stream import materialize
+from mirage.workspace.executor.builtins.xargs import handle_xargs
+from mirage.workspace.session.session import Session
+
+
+class FakeShell:
+
+    def __init__(self, exit_codes: list[int] | None = None):
+        self.lines: list[str] = []
+        self.exit_codes = exit_codes or []
+
+    async def __call__(self, line: str, session_id: str) -> IOResult:
+        self.lines.append(line)
+        code = (self.exit_codes[len(self.lines) - 1]
+                if len(self.lines) <= len(self.exit_codes) else 0)
+        return IOResult(stdout=f"ran:{line}\n".encode(), exit_code=code)
+
+
+def make_session() -> Session:
+    return Session(session_id="s1")
+
+
+@pytest.mark.asyncio
+async def test_batches_one_arg_per_run_with_n1():
+    shell = FakeShell()
+    _, io, _ = await handle_xargs(shell, ["-n1", "echo"], make_session(),
+                                  b"a b c")
+    assert shell.lines == ["echo a", "echo b", "echo c"]
+    assert io.exit_code == 0
+
+
+@pytest.mark.asyncio
+async def test_single_run_without_n():
+    shell = FakeShell()
+    _, io, _ = await handle_xargs(shell, ["echo"], make_session(), b"a b c")
+    assert shell.lines == ["echo a b c"]
+    assert io.exit_code == 0
+
+
+@pytest.mark.asyncio
+async def test_failing_invocation_exits_123_but_continues():
+    shell = FakeShell(exit_codes=[1, 0])
+    _, io, _ = await handle_xargs(shell, ["-n1", "wc"], make_session(), b"a b")
+    assert shell.lines == ["wc a", "wc b"]
+    assert io.exit_code == 123
+
+
+@pytest.mark.asyncio
+async def test_command_not_found_stops_with_127():
+    shell = FakeShell(exit_codes=[127, 0])
+    _, io, _ = await handle_xargs(shell, ["-n1", "nope"], make_session(),
+                                  b"a b")
+    assert shell.lines == ["nope a"]
+    assert io.exit_code == 127
+
+
+@pytest.mark.asyncio
+async def test_no_run_if_empty():
+    shell = FakeShell()
+    _, io, _ = await handle_xargs(shell, ["-r", "echo", "hi"], make_session(),
+                                  b"")
+    assert shell.lines == []
+    assert io.exit_code == 0
+
+
+@pytest.mark.asyncio
+async def test_empty_input_without_r_runs_once():
+    shell = FakeShell()
+    _, io, _ = await handle_xargs(shell, ["echo", "hi"], make_session(), b"")
+    assert shell.lines == ["echo hi"]
+    assert io.exit_code == 0
+
+
+@pytest.mark.asyncio
+async def test_null_delimited_input():
+    shell = FakeShell()
+    await handle_xargs(shell, ["-0", "echo"], make_session(), b"a b\0c\0")
+    assert shell.lines == ["echo 'a b' c"]
+
+
+@pytest.mark.asyncio
+async def test_custom_delimiter():
+    shell = FakeShell()
+    await handle_xargs(shell, ["-d,", "echo"], make_session(), b"a,b,c")
+    assert shell.lines == ["echo a b c"]
+
+
+@pytest.mark.asyncio
+async def test_invalid_option_exits_1():
+    shell = FakeShell()
+    _, io, _ = await handle_xargs(shell, ["-q", "echo"], make_session(), b"x")
+    assert io.exit_code == 1
+    assert await materialize(io.stderr) == b"xargs: invalid option -- 'q'\n"
+    assert shell.lines == []
+
+
+@pytest.mark.asyncio
+async def test_unsupported_option_exits_1():
+    shell = FakeShell()
+    _, io, _ = await handle_xargs(shell, ["-I", "{}", "echo"], make_session(),
+                                  b"x")
+    assert io.exit_code == 1
+    assert await materialize(io.stderr
+                             ) == b"xargs: unsupported option -- 'I'\n"
+
+
+@pytest.mark.asyncio
+async def test_n_zero_rejected():
+    shell = FakeShell()
+    _, io, _ = await handle_xargs(shell, ["-n0", "echo"], make_session(), b"x")
+    assert io.exit_code == 1
+    assert (await
+            materialize(io.stderr
+                        )) == b"xargs: value 0 for -n option should be >= 1\n"
+
+
+@pytest.mark.asyncio
+async def test_input_words_stay_single_tokens():
+    shell = FakeShell()
+    await handle_xargs(shell, ["echo"], make_session(), b"don't $(reboot)")
+    assert shell.lines == ["echo 'don'\"'\"'t' '$(reboot)'"]