chore: import upstream snapshot with attribution

python/tests/commands/builtin/utils/__init__.py

@@ -0,0 +1,13 @@
+# ========= 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. =========

python/tests/commands/builtin/utils/test_cancellation.py

@@ -0,0 +1,89 @@
+# ========= 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 asyncio
+import time
+
+import pytest
+
+from mirage.commands.builtin.utils.safeguard import (CommandTimeoutError,
+                                                     run_with_timeout,
+                                                     with_timeout)
+from mirage.io.types import materialize
+
+
+class _Probe:
+
+    def __init__(self) -> None:
+        self.closed = False
+
+
+async def _clean_producer(probe: _Probe):
+    try:
+        await asyncio.sleep(5)
+        yield b"x"
+    finally:
+        probe.closed = True
+
+
+async def _leaky_producer(probe: _Probe):
+    try:
+        await asyncio.sleep(5)
+        yield b"x"
+    except asyncio.CancelledError:
+        await asyncio.sleep(0.4)
+        probe.closed = True
+        raise
+
+
+async def _clean_coro(probe: _Probe):
+    try:
+        await asyncio.sleep(5)
+    finally:
+        probe.closed = True
+
+
+@pytest.mark.asyncio
+async def test_with_timeout_releases_resource_on_cancel():
+    probe = _Probe()
+    with pytest.raises(CommandTimeoutError):
+        await materialize(with_timeout(_clean_producer(probe), 0.05, "cat"))
+    assert probe.closed
+
+
+@pytest.mark.asyncio
+async def test_with_timeout_fires_promptly_for_clean_producer():
+    start = time.monotonic()
+    with pytest.raises(CommandTimeoutError):
+        await materialize(with_timeout(_clean_producer(_Probe()), 0.05, "cat"))
+    assert time.monotonic() - start < 0.3
+
+
+@pytest.mark.asyncio
+async def test_with_timeout_unwind_is_handler_controlled():
+    start = time.monotonic()
+    probe = _Probe()
+    with pytest.raises(CommandTimeoutError):
+        await materialize(with_timeout(_leaky_producer(probe), 0.05, "cat"))
+    elapsed = time.monotonic() - start
+    assert probe.closed
+    assert elapsed >= 0.4
+
+
+@pytest.mark.asyncio
+async def test_run_with_timeout_releases_resource_on_cancel():
+    probe = _Probe()
+    with pytest.raises(CommandTimeoutError):
+        await run_with_timeout(_clean_coro(probe), 0.05, "stat")
+    assert probe.closed

python/tests/commands/builtin/utils/test_formatting.py

@@ -0,0 +1,42 @@
+# ========= 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. =========
+
+from mirage.commands.builtin.utils.formatting import (_human_size,
+                                                      format_number,
+                                                      parse_size, to_number)
+
+
+def testparse_size_plain_and_human():
+    assert parse_size("123") == 123
+    assert parse_size("4.0K") == 4096
+    assert parse_size("2.5M") == 2621440
+    assert parse_size("7B") == 7
+
+
+def testparse_size_inverts_human_size():
+    for n in (0, 512, 4096, 1024**2, 3 * 1024**3):
+        assert parse_size(_human_size(n)) == n
+
+
+def test_to_number_gnu_awk_coercion():
+    assert to_number("3") == 3.0
+    assert to_number("2.5x") == 2.5
+    assert to_number("abc") == 0.0
+    assert to_number(" -4.5 ") == -4.5
+    assert to_number("1e3zzz") == 1000.0
+
+
+def test_format_number_collapses_integral_floats():
+    assert format_number(60.0) == "60"
+    assert format_number(5.5) == "5.5"

python/tests/commands/builtin/utils/test_output.py

@@ -0,0 +1,23 @@
+from mirage.commands.builtin.utils.output import (format_optional_records,
+                                                  format_record_text,
+                                                  format_records)
+
+
+def test_format_records_empty_returns_empty_bytes():
+    assert format_records([]) == b""
+
+
+def test_format_records_single_record_terminates_line():
+    assert format_records(["a"]) == b"a\n"
+
+
+def test_format_records_multiple_records_terminates_last_line():
+    assert format_records(["a", "b"]) == b"a\nb\n"
+
+
+def test_format_optional_records_empty_returns_none():
+    assert format_optional_records([]) is None
+
+
+def test_format_record_text_multiple_records_terminates_last_line():
+    assert format_record_text(["a", "b"]) == "a\nb\n"

python/tests/commands/builtin/utils/test_paths.py

@@ -0,0 +1,39 @@
+# ========= 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. =========
+
+from mirage.commands.builtin.utils.paths import default_paths
+from mirage.types import PathSpec
+
+
+def _spec(virtual: str) -> PathSpec:
+    return PathSpec(virtual=virtual,
+                    directory=virtual,
+                    resource_path=virtual.strip("/"))
+
+
+def test_non_empty_paths_pass_through():
+    operands = [_spec("/mnt/a"), _spec("/mnt/b")]
+    assert default_paths(operands, _spec("/cwd")) == operands
+
+
+def test_empty_paths_fall_back_to_cwd():
+    cwd = _spec("/cwd")
+    assert default_paths([], cwd) == [cwd]
+
+
+def test_empty_paths_without_cwd_default_to_root():
+    result = default_paths([], None)
+    assert len(result) == 1
+    assert result[0].virtual == "/"
+    assert result[0].resource_path == ""

python/tests/commands/builtin/utils/test_safeguard.py

@@ -0,0 +1,139 @@
+# ========= 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 asyncio
+from collections.abc import AsyncIterator
+
+import pytest
+
+from mirage.commands.builtin.utils.safeguard import (CommandTimeoutError,
+                                                     apply_safeguard,
+                                                     maybe_with_timeout,
+                                                     run_with_timeout)
+from mirage.commands.safeguard import CommandSafeguard
+from mirage.io.types import materialize
+from mirage.types import OnExceed
+
+_TEN = b"".join(f"line{i}\n".encode() for i in range(10))
+
+
+async def _stream(data: bytes) -> AsyncIterator[bytes]:
+    for i in range(0, len(data), 7):
+        yield data[i:i + 7]
+
+
+async def _slow_stream() -> AsyncIterator[bytes]:
+    await asyncio.sleep(5)
+    yield b"x"
+
+
+async def _const(value):
+    return value
+
+
+async def _sleep_forever():
+    await asyncio.sleep(5)
+
+
+@pytest.mark.asyncio
+async def test_no_safeguard_passthrough():
+    out, io = await apply_safeguard(_TEN, None)
+    assert out == _TEN and io.exit_code == 0 and io.stderr is None
+
+
+@pytest.mark.asyncio
+async def test_under_limit_not_truncated():
+    sg = CommandSafeguard(max_lines=100)
+    out, io = await apply_safeguard(_TEN, sg)
+    assert out == _TEN and io.stderr is None
+
+
+@pytest.mark.asyncio
+async def test_truncate_by_lines():
+    sg = CommandSafeguard(max_lines=3)
+    out, io = await apply_safeguard(_TEN, sg)
+    assert out == b"line0\nline1\nline2\n"
+    assert io.exit_code == 0
+    assert b"truncated" in (await materialize(io.stderr))
+
+
+@pytest.mark.asyncio
+async def test_error_by_lines():
+    sg = CommandSafeguard(max_lines=3, on_exceed=OnExceed.ERROR)
+    out, io = await apply_safeguard(_TEN, sg)
+    assert out is None
+    assert io.exit_code == 1
+    assert b"truncated" in (await materialize(io.stderr))
+
+
+@pytest.mark.asyncio
+async def test_truncate_by_bytes():
+    sg = CommandSafeguard(max_bytes=10)
+    out, io = await apply_safeguard(_TEN, sg)
+    assert out == _TEN[:10]
+    assert b"truncated" in (await materialize(io.stderr))
+
+
+@pytest.mark.asyncio
+async def test_streaming_input_truncates_and_stops_early():
+    sg = CommandSafeguard(max_lines=2)
+    out, io = await apply_safeguard(_stream(_TEN), sg)
+    assert out == b"line0\nline1\n"
+    assert b"truncated" in (await materialize(io.stderr))
+
+
+def test_maybe_with_timeout_passthrough_when_no_safeguard():
+    stream = _stream(_TEN)
+    assert maybe_with_timeout(stream, None, "cat") is stream
+
+
+def test_maybe_with_timeout_passthrough_when_bytes():
+    assert maybe_with_timeout(_TEN, CommandSafeguard(timeout_seconds=1),
+                              "cat") == _TEN
+
+
+def test_maybe_with_timeout_passthrough_when_no_timeout():
+    stream = _stream(_TEN)
+    assert maybe_with_timeout(stream, CommandSafeguard(max_lines=3),
+                              "cat") is stream
+
+
+def test_maybe_with_timeout_passthrough_when_nonpositive():
+    stream = _stream(_TEN)
+    assert maybe_with_timeout(stream, CommandSafeguard(timeout_seconds=0),
+                              "cat") is stream
+
+
+@pytest.mark.asyncio
+async def test_maybe_with_timeout_wraps_and_fires():
+    wrapped = maybe_with_timeout(_slow_stream(),
+                                 CommandSafeguard(timeout_seconds=0.1), "cat")
+    with pytest.raises(CommandTimeoutError):
+        await materialize(wrapped)
+
+
+@pytest.mark.asyncio
+async def test_run_with_timeout_returns_result_when_under_budget():
+    assert await run_with_timeout(_const(42), 1.0, "sleep") == 42
+
+
+@pytest.mark.asyncio
+async def test_run_with_timeout_no_timeout_when_seconds_falsy():
+    assert await run_with_timeout(_const(7), None, "sleep") == 7
+
+
+@pytest.mark.asyncio
+async def test_run_with_timeout_raises_on_overrun():
+    with pytest.raises(CommandTimeoutError):
+        await run_with_timeout(_sleep_forever(), 0.1, "sleep")