chore: import upstream snapshot with attribution

python/tests/commands/builtin/github/__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/github/conftest.py

@@ -0,0 +1,35 @@
+# ========= 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.resource.github.github import GitHubResource
+from tests.fixtures.github_mock import github_config, mock_github_api
+
+__all__ = ["github_config", "mock_github_api"]
+
+OWNER = "test-owner"
+REPO = "test-repo"
+REF = "main"
+
+
+@pytest.fixture
+def github_env(mock_github_api, github_config):
+    resource = GitHubResource(
+        config=github_config,
+        owner=OWNER,
+        repo=REPO,
+        ref=REF,
+    )
+    return resource.accessor, resource._index

python/tests/commands/builtin/github/test_grep.py

@@ -0,0 +1,166 @@
+# ========= 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.commands.builtin.github.grep import grep
+from mirage.io.stream import materialize
+from mirage.types import PathSpec
+from mirage.utils.key_prefix import mount_key
+from tests.fixtures.github_mock import MOCK_BLOBS
+
+
+@pytest.fixture(autouse=True)
+def _patch_read(monkeypatch):
+
+    async def _read_bytes(config, owner, repo, sha):
+        return MOCK_BLOBS[sha]
+
+    monkeypatch.setattr("mirage.core.github.read.read_bytes", _read_bytes)
+
+
+def _scope(path: str, resolved: bool = True) -> PathSpec:
+    norm = "/" + path.lstrip("/")
+    directory = norm.rsplit("/", 1)[0] + "/"
+    return PathSpec(resource_path=(norm).strip("/"),
+                    virtual=norm,
+                    directory=directory,
+                    resolved=resolved)
+
+
+async def _run(accessor, index, paths, pattern, **kwargs):
+    scopes = [_scope(p, resolved=("." in p.split("/")[-1])) for p in paths]
+    stdout, io = await grep(accessor, scopes, pattern, index=index, **kwargs)
+    data = await materialize(stdout)
+    return data.decode(errors="replace"), io
+
+
+@pytest.mark.asyncio
+async def test_single_file_grep(mock_github_api, github_env):
+    accessor, index = github_env
+    text, io = await _run(accessor, index, ["src/main.py"], "import")
+    assert io.exit_code == 0
+    lines = text.strip().splitlines()
+    assert len(lines) == 3
+    assert "import os" in lines[0]
+    assert "import sys" in lines[1]
+    assert "import helper" in lines[2]
+
+
+@pytest.mark.asyncio
+async def test_grep_with_line_numbers(mock_github_api, github_env):
+    accessor, index = github_env
+    text, io = await _run(accessor, index, ["src/main.py"], "import", n=True)
+    assert io.exit_code == 0
+    lines = text.strip().splitlines()
+    assert lines[0].startswith("1:")
+    assert lines[1].startswith("2:")
+
+
+@pytest.mark.asyncio
+async def test_grep_case_insensitive(mock_github_api, github_env):
+    accessor, index = github_env
+    text, io = await _run(accessor, index, ["src/main.py"], "IMPORT", i=True)
+    assert io.exit_code == 0
+    lines = text.strip().splitlines()
+    assert len(lines) >= 2
+
+
+@pytest.mark.asyncio
+async def test_grep_invert(mock_github_api, github_env):
+    accessor, index = github_env
+    text, io = await _run(accessor, index, ["src/utils.py"], "import", v=True)
+    assert io.exit_code == 0
+    lines = text.strip().splitlines()
+    for line in lines:
+        assert "import" not in line
+
+
+@pytest.mark.asyncio
+async def test_grep_count(mock_github_api, github_env):
+    accessor, index = github_env
+    text, io = await _run(accessor, index, ["src/main.py"], "import", c=True)
+    assert io.exit_code == 0
+    assert text.strip() == "3"
+
+
+@pytest.mark.asyncio
+async def test_recursive_grep(mock_github_api, github_env):
+    accessor, index = github_env
+    text, io = await _run(accessor, index, ["src"], "dataclass", r=True)
+    assert io.exit_code == 0
+    lines = text.strip().splitlines()
+    assert len(lines) >= 2
+    paths_found = [line.split(":")[0] for line in lines]
+    assert any("user.py" in p for p in paths_found)
+    assert any("item.py" in p for p in paths_found)
+
+
+@pytest.mark.asyncio
+async def test_grep_no_match(mock_github_api, github_env):
+    accessor, index = github_env
+    text, io = await _run(accessor, index, ["src/main.py"], "zzz_no_match_zzz")
+    assert io.exit_code == 1
+
+
+@pytest.mark.asyncio
+async def test_grep_files_only(mock_github_api, github_env):
+    accessor, index = github_env
+    text, io = await _run(accessor,
+                          index, ["src"],
+                          "dataclass",
+                          r=True,
+                          args_l=True)
+    assert io.exit_code == 0
+    lines = text.strip().splitlines()
+    assert any("user.py" in ln for ln in lines)
+    assert any("item.py" in ln for ln in lines)
+
+
+@pytest.mark.asyncio
+async def test_grep_stdin(github_env):
+    accessor, index = github_env
+    stdin_data = b"hello world\nfoo bar\nhello again\n"
+    stdout, io = await grep(accessor, [],
+                            "hello",
+                            stdin=stdin_data,
+                            index=index)
+    data = await materialize(stdout)
+    text = data.decode(errors="replace")
+    lines = text.strip().splitlines()
+    assert len(lines) == 2
+    assert "hello world" in lines[0]
+    assert "hello again" in lines[1]
+
+
+@pytest.mark.asyncio
+async def test_grep_files_only_with_prefix(mock_github_api, github_env):
+    accessor, index = github_env
+    scopes = [
+        PathSpec(resource_path=mount_key("/gh/src", "/gh"),
+                 virtual="/gh/src",
+                 directory="/gh/src/",
+                 resolved=False)
+    ]
+    stdout, io = await grep(accessor,
+                            scopes,
+                            "dataclass",
+                            r=True,
+                            args_l=True,
+                            index=index)
+    data = await materialize(stdout)
+    text = data.decode()
+    assert io.exit_code == 0
+    lines = text.strip().splitlines()
+    assert any("user.py" in ln for ln in lines)

python/tests/commands/builtin/github/test_grep_search.py

@@ -0,0 +1,120 @@
+# ========= 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 unittest.mock import AsyncMock
+
+import pytest
+
+from mirage.commands.builtin.github.grep import grep
+from mirage.commands.builtin.github.narrow import narrow_scope
+from mirage.types import PathSpec
+from tests.fixtures.github_mock import MOCK_BLOBS
+
+_GLOBALS = grep.__wrapped__.__globals__
+_NGLOBALS = narrow_scope.__globals__
+
+
+@pytest.fixture(autouse=True)
+def _patch_read(monkeypatch):
+
+    async def _read_bytes(config, owner, repo, sha):
+        return MOCK_BLOBS[sha]
+
+    monkeypatch.setattr("mirage.core.github.read.read_bytes", _read_bytes)
+
+
+def _root() -> PathSpec:
+    return PathSpec(resource_path="",
+                    virtual="/",
+                    directory="/",
+                    resolved=False)
+
+
+def _subdir() -> PathSpec:
+    return PathSpec(resource_path="src",
+                    virtual="/src",
+                    directory="/src",
+                    resolved=False)
+
+
+@pytest.mark.asyncio
+async def test_grep_root_large_tree_uses_search(mock_github_api, github_env,
+                                                monkeypatch):
+    accessor, index = github_env
+    narrowed = [
+        PathSpec(resource_path="src/main.py",
+                 virtual="/src/main.py",
+                 directory="",
+                 resolved=True),
+    ]
+    spy = AsyncMock(return_value=narrowed)
+    monkeypatch.setitem(_NGLOBALS, "SCOPE_WARN", 1)
+    monkeypatch.setitem(_NGLOBALS, "narrow_paths", spy)
+    await grep(accessor, [_root()], "import", r=True, index=index)
+    spy.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_grep_subdir_uses_search(mock_github_api, github_env,
+                                       monkeypatch):
+    accessor, index = github_env
+    spy = AsyncMock(return_value=[])
+    monkeypatch.setitem(_NGLOBALS, "SCOPE_WARN", 1)
+    monkeypatch.setitem(_NGLOBALS, "narrow_paths", spy)
+    await grep(accessor, [_subdir()], "import", r=True, index=index)
+    spy.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_grep_regex_with_literal_uses_search(mock_github_api, github_env,
+                                                   monkeypatch):
+    accessor, index = github_env
+    spy = AsyncMock(return_value=[])
+    monkeypatch.setitem(_NGLOBALS, "SCOPE_WARN", 1)
+    monkeypatch.setitem(_NGLOBALS, "narrow_paths", spy)
+    await grep(accessor, [_root()], "import.*os", r=True, index=index)
+    spy.assert_awaited_once()
+    assert spy.await_args.args[3] == "import"
+
+
+@pytest.mark.asyncio
+async def test_grep_regex_without_literal_skips_search(mock_github_api,
+                                                       github_env,
+                                                       monkeypatch):
+    accessor, index = github_env
+    spy = AsyncMock(return_value=[])
+    monkeypatch.setitem(_NGLOBALS, "SCOPE_WARN", 1)
+    monkeypatch.setitem(_NGLOBALS, "narrow_paths", spy)
+    await grep(accessor, [_root()], "import|export", r=True, index=index)
+    spy.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_grep_small_tree_skips_search(mock_github_api, github_env,
+                                            monkeypatch):
+    accessor, index = github_env
+    spy = AsyncMock(return_value=[])
+    monkeypatch.setitem(_NGLOBALS, "narrow_paths", spy)
+    await grep(accessor, [_root()], "import", r=True, index=index)
+    spy.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_grep_scope_error_when_too_many_files(mock_github_api,
+                                                    github_env, monkeypatch):
+    accessor, index = github_env
+    monkeypatch.setitem(_GLOBALS, "SCOPE_ERROR", 1)
+    stdout, io = await grep(accessor, [_root()], "import", r=True, index=index)
+    assert io.exit_code == 1
+    assert b"narrow the path" in (io.stderr or b"")

python/tests/commands/builtin/github/test_narrow.py

@@ -0,0 +1,192 @@
+# ========= 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.commands.builtin.github.grep import grep
+from mirage.commands.builtin.github.narrow import narrow_scope
+from mirage.commands.builtin.github.rg import rg
+from mirage.io.stream import materialize
+from mirage.types import PathSpec
+from tests.fixtures.github_mock import MOCK_BLOBS
+
+_NGLOBALS = narrow_scope.__globals__
+
+
+@pytest.fixture
+def counting_read(monkeypatch):
+    reads: list[str] = []
+
+    async def _read_bytes(config, owner, repo, sha):
+        reads.append(sha)
+        return MOCK_BLOBS.get(sha, b"")
+
+    monkeypatch.setattr("mirage.core.github.read.read_bytes", _read_bytes)
+    return reads
+
+
+def _root() -> PathSpec:
+    return PathSpec(resource_path="",
+                    virtual="/",
+                    directory="/",
+                    resolved=False)
+
+
+def _subdir() -> PathSpec:
+    return PathSpec(resource_path="src",
+                    virtual="/src",
+                    directory="/src",
+                    resolved=False)
+
+
+@pytest.mark.asyncio
+async def test_subdir_narrows_and_fetches_fewer(mock_github_api, github_env,
+                                                counting_read, monkeypatch):
+    accessor, index = github_env
+    monkeypatch.setitem(_NGLOBALS, "SCOPE_WARN", 1)
+    await grep(accessor, [_subdir()], "import", r=True, index=index)
+    # /src holds 7 files; code search narrows to the import-matching subset.
+    assert 0 < len(counting_read) < 7
+
+
+@pytest.mark.asyncio
+async def test_regex_narrows_via_extracted_literal(mock_github_api, github_env,
+                                                   counting_read, monkeypatch):
+    accessor, index = github_env
+    monkeypatch.setitem(_NGLOBALS, "SCOPE_WARN", 1)
+    await grep(accessor, [_root()], "import.*os", r=True, index=index)
+    # "import" is the required literal; only files containing it are fetched.
+    assert 0 < len(counting_read) < len(MOCK_BLOBS)
+
+
+@pytest.mark.asyncio
+async def test_files_only_shortcircuit_reads_nothing(mock_github_api,
+                                                     github_env, counting_read,
+                                                     monkeypatch):
+    accessor, index = github_env
+    monkeypatch.setitem(_NGLOBALS, "SCOPE_WARN", 1)
+    stdout, io = await grep(accessor, [_root()],
+                            "import",
+                            r=True,
+                            args_l=True,
+                            index=index)
+    body = (await materialize(stdout)).decode()
+    assert len(counting_read) == 0
+    assert io.exit_code == 0
+    assert "src/main.py" in body
+
+
+@pytest.mark.asyncio
+async def test_files_only_shortcircuit_matches_generic(mock_github_api,
+                                                       github_env,
+                                                       monkeypatch):
+    accessor, index = github_env
+
+    monkeypatch.setitem(_NGLOBALS, "SCOPE_WARN", 10_000)
+    out_generic, _ = await grep(accessor, [_root()],
+                                "import",
+                                r=True,
+                                args_l=True,
+                                index=index)
+    text_generic = (await materialize(out_generic)).decode()
+
+    monkeypatch.setitem(_NGLOBALS, "SCOPE_WARN", 1)
+    out_short, _ = await grep(accessor, [_root()],
+                              "import",
+                              r=True,
+                              args_l=True,
+                              index=index)
+    text_short = (await materialize(out_short)).decode()
+
+    assert text_short == text_generic
+    assert text_short
+
+
+@pytest.mark.asyncio
+async def test_rg_files_only_shortcircuit_reads_nothing(
+        mock_github_api, github_env, counting_read, monkeypatch):
+    accessor, index = github_env
+    monkeypatch.setitem(_NGLOBALS, "SCOPE_WARN", 1)
+    stdout, io = await rg(accessor, [_root()],
+                          "import",
+                          args_l=True,
+                          index=index)
+    body = (await materialize(stdout)).decode()
+    assert len(counting_read) == 0
+    assert io.exit_code == 0
+    assert "src/main.py" in body
+
+
+@pytest.mark.asyncio
+async def test_rg_files_only_shortcircuit_matches_generic(
+        mock_github_api, github_env, monkeypatch):
+    accessor, index = github_env
+
+    monkeypatch.setitem(_NGLOBALS, "SCOPE_WARN", 10_000)
+    out_generic, _ = await rg(accessor, [_root()],
+                              "import",
+                              args_l=True,
+                              index=index)
+    text_generic = (await materialize(out_generic)).decode()
+
+    monkeypatch.setitem(_NGLOBALS, "SCOPE_WARN", 1)
+    out_short, _ = await rg(accessor, [_root()],
+                            "import",
+                            args_l=True,
+                            index=index)
+    text_short = (await materialize(out_short)).decode()
+
+    assert text_short == text_generic
+    assert text_short
+
+
+@pytest.mark.asyncio
+async def test_rg_files_only_shortcircuit_respects_glob(
+        mock_github_api, github_env, monkeypatch):
+    accessor, index = github_env
+
+    monkeypatch.setitem(_NGLOBALS, "SCOPE_WARN", 10_000)
+    out_generic, _ = await rg(accessor, [_root()],
+                              "import",
+                              args_l=True,
+                              glob="main*.py",
+                              index=index)
+    text_generic = (await materialize(out_generic)).decode()
+
+    monkeypatch.setitem(_NGLOBALS, "SCOPE_WARN", 1)
+    out_short, _ = await rg(accessor, [_root()],
+                            "import",
+                            args_l=True,
+                            glob="main*.py",
+                            index=index)
+    text_short = (await materialize(out_short)).decode()
+
+    assert text_short == text_generic
+    assert "main.py" in text_short
+    assert "utils.py" not in text_short
+
+
+@pytest.mark.asyncio
+async def test_rg_shortcircuit_no_match_exit_1(mock_github_api, github_env,
+                                               monkeypatch):
+    accessor, index = github_env
+    monkeypatch.setitem(_NGLOBALS, "SCOPE_WARN", 1)
+    stdout, io = await rg(accessor, [_root()],
+                          "import",
+                          args_l=True,
+                          glob="*.nomatch",
+                          index=index)
+    body = (await materialize(stdout)).decode()
+    assert io.exit_code == 1
+    assert body == ""

python/tests/commands/builtin/github/test_read_helper.py

@@ -0,0 +1,58 @@
+# ========= 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.cache.index.ram import RAMIndexCacheStore
+from mirage.core.github.read import read as github_read
+from tests.fixtures.github_mock import MOCK_BLOBS
+
+
+@pytest.fixture(autouse=True)
+def _patch_read(monkeypatch):
+
+    async def _read_bytes(config, owner, repo, sha):
+        return MOCK_BLOBS[sha]
+
+    monkeypatch.setattr("mirage.core.github.read.read_bytes", _read_bytes)
+
+
+@pytest.mark.asyncio
+async def test_read_valid_blob(github_env):
+    accessor, index = github_env
+    data = await github_read(accessor, "/README.md", index)
+    assert isinstance(data, bytes)
+    assert b"Mock Repo" in data
+
+
+@pytest.mark.asyncio
+async def test_read_missing_path(github_env):
+    accessor, index = github_env
+    with pytest.raises(FileNotFoundError):
+        await github_read(accessor, "/nonexistent.txt", index)
+
+
+@pytest.mark.asyncio
+async def test_read_empty_index(github_env):
+    accessor, _ = github_env
+    empty_index = RAMIndexCacheStore()
+    with pytest.raises(FileNotFoundError):
+        await github_read(accessor, "/README.md", empty_index)
+
+
+@pytest.mark.asyncio
+async def test_read_directory_path(github_env):
+    accessor, index = github_env
+    with pytest.raises(IsADirectoryError):
+        await github_read(accessor, "/src", index)

python/tests/commands/builtin/github/test_rg_search.py

@@ -0,0 +1,127 @@
+# ========= 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 unittest.mock import AsyncMock
+
+import pytest
+
+from mirage.commands.builtin.github.narrow import narrow_scope
+from mirage.commands.builtin.github.rg import rg
+from mirage.io.stream import materialize
+from mirage.types import PathSpec
+from tests.fixtures.github_mock import MOCK_BLOBS
+
+_GLOBALS = rg.__wrapped__.__globals__
+_NGLOBALS = narrow_scope.__globals__
+
+
+@pytest.fixture(autouse=True)
+def _patch_read(monkeypatch):
+
+    async def _read_bytes(config, owner, repo, sha):
+        return MOCK_BLOBS[sha]
+
+    monkeypatch.setattr("mirage.core.github.read.read_bytes", _read_bytes)
+
+
+def _root() -> PathSpec:
+    return PathSpec(resource_path="",
+                    virtual="/",
+                    directory="/",
+                    resolved=False)
+
+
+def _subdir() -> PathSpec:
+    return PathSpec(resource_path="src",
+                    virtual="/src",
+                    directory="/src",
+                    resolved=False)
+
+
+@pytest.mark.asyncio
+async def test_rg_root_large_tree_uses_search(mock_github_api, github_env,
+                                              monkeypatch):
+    accessor, index = github_env
+    narrowed = [
+        PathSpec(resource_path="src/main.py",
+                 virtual="/src/main.py",
+                 directory="",
+                 resolved=True),
+        PathSpec(resource_path="src/utils.py",
+                 virtual="/src/utils.py",
+                 directory="",
+                 resolved=True),
+    ]
+    spy = AsyncMock(return_value=narrowed)
+    monkeypatch.setitem(_NGLOBALS, "SCOPE_WARN", 1)
+    monkeypatch.setitem(_NGLOBALS, "narrow_paths", spy)
+    stdout, io = await rg(accessor, [_root()], "import", c=True, index=index)
+    spy.assert_awaited_once()
+    text = (await materialize(stdout)).decode()
+    assert io.exit_code == 0
+    assert "/src/main.py:3" in text
+    assert "/src/utils.py:1" in text
+
+
+@pytest.mark.asyncio
+async def test_rg_subdir_uses_search(mock_github_api, github_env, monkeypatch):
+    accessor, index = github_env
+    spy = AsyncMock(return_value=[])
+    monkeypatch.setitem(_NGLOBALS, "SCOPE_WARN", 1)
+    monkeypatch.setitem(_NGLOBALS, "narrow_paths", spy)
+    await rg(accessor, [_subdir()], "import", index=index)
+    spy.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_rg_regex_with_literal_uses_search(mock_github_api, github_env,
+                                                 monkeypatch):
+    accessor, index = github_env
+    spy = AsyncMock(return_value=[])
+    monkeypatch.setitem(_NGLOBALS, "SCOPE_WARN", 1)
+    monkeypatch.setitem(_NGLOBALS, "narrow_paths", spy)
+    await rg(accessor, [_root()], "imp.*rt", index=index)
+    spy.assert_awaited_once()
+    assert spy.await_args.args[3] == "imp"
+
+
+@pytest.mark.asyncio
+async def test_rg_regex_without_literal_skips_search(mock_github_api,
+                                                     github_env, monkeypatch):
+    accessor, index = github_env
+    spy = AsyncMock(return_value=[])
+    monkeypatch.setitem(_NGLOBALS, "SCOPE_WARN", 1)
+    monkeypatch.setitem(_NGLOBALS, "narrow_paths", spy)
+    await rg(accessor, [_root()], "imp|exp", index=index)
+    spy.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_rg_small_tree_skips_search(mock_github_api, github_env,
+                                          monkeypatch):
+    accessor, index = github_env
+    spy = AsyncMock(return_value=[])
+    monkeypatch.setitem(_NGLOBALS, "narrow_paths", spy)
+    await rg(accessor, [_root()], "import", index=index)
+    spy.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_rg_scope_error_when_too_many_files(mock_github_api, github_env,
+                                                  monkeypatch):
+    accessor, index = github_env
+    monkeypatch.setitem(_GLOBALS, "SCOPE_ERROR", 1)
+    stdout, io = await rg(accessor, [_root()], "import", index=index)
+    assert io.exit_code == 1
+    assert b"narrow the path" in (io.stderr or b"")

python/tests/commands/builtin/github/test_sed.py

@@ -0,0 +1,103 @@
+# ========= 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. =========
+"""sed over the read-only GitHub mount (factory-built command).
+
+GitHub is read-only: `sed` is a read-transform (output to stdout) and `-i` is
+rejected. Exercises the generic sed builder wiring for github (index-aware
+read, write-gated -i).
+"""
+
+import pytest
+
+from mirage.commands.builtin.github import COMMANDS
+from mirage.io.stream import materialize
+from mirage.types import PathSpec
+from tests.fixtures.github_mock import MOCK_BLOBS
+
+
+@pytest.fixture(autouse=True)
+def _patch_read(monkeypatch):
+
+    async def _read_bytes(config, owner, repo, sha):
+        return MOCK_BLOBS[sha]
+
+    monkeypatch.setattr("mirage.core.github.read.read_bytes", _read_bytes)
+
+
+def _sed_command():
+    for cmd in COMMANDS:
+        for rc in cmd._registered_commands:
+            if rc.name == "sed":
+                return cmd
+    raise LookupError("sed not registered for github")
+
+
+sed = _sed_command()
+
+
+def _scope(path: str) -> PathSpec:
+    norm = "/" + path.lstrip("/")
+    directory = norm.rsplit("/", 1)[0] + "/"
+    return PathSpec(resource_path=(norm).strip("/"),
+                    virtual=norm,
+                    directory=directory,
+                    resolved=True)
+
+
+async def _run(accessor, index, path, expr, **kwargs):
+    stdout, io = await sed(accessor, [_scope(path)],
+                           expr,
+                           index=index,
+                           **kwargs)
+    data = await materialize(stdout) if stdout is not None else b""
+    return data.decode(errors="replace"), io
+
+
+@pytest.mark.asyncio
+async def test_sed_read_transform(mock_github_api, github_env):
+    accessor, index = github_env
+    text, io = await _run(accessor, index, "src/main.py", "s/import/IMPORT/")
+    assert io.exit_code == 0
+    # First match on each line (non-global), matching GNU sed.
+    assert text == ("IMPORT os\nIMPORT sys\n"
+                    "from src.utils IMPORT helper\n"
+                    "\nasync def main():\n    pass\n")
+
+
+@pytest.mark.asyncio
+async def test_sed_global(mock_github_api, github_env):
+    accessor, index = github_env
+    text, io = await _run(accessor, index, "src/utils.py", "s/e/E/g")
+    assert io.exit_code == 0
+    assert "dEf hElpEr():" in text
+    assert "rEturn 42" in text
+
+
+@pytest.mark.asyncio
+async def test_sed_address_delete(mock_github_api, github_env):
+    accessor, index = github_env
+    text, io = await _run(accessor, index, "src/main.py", "/^import/d")
+    assert io.exit_code == 0
+    # The two leading `import` lines are dropped; `from ... import` stays.
+    assert "import os" not in text
+    assert "import sys" not in text
+    assert "from src.utils import helper" in text
+
+
+@pytest.mark.asyncio
+async def test_sed_inplace_rejected(mock_github_api, github_env):
+    accessor, index = github_env
+    with pytest.raises(PermissionError,
+                       match="-i not supported on this backend"):
+        await _run(accessor, index, "src/main.py", "s/import/X/", i=True)