chore: import upstream snapshot with attribution

python/mirage/core/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/mirage/core/github/_client.py

@@ -0,0 +1,61 @@
+# ========= 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 json
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+import aiohttp
+
+from mirage.resource.secrets import reveal_secret
+from mirage.types import PathSpec
+
+API_BASE = "https://api.github.com"
+API_VERSION = "2022-11-28"
+
+
+def github_headers(token: str) -> dict[str, str]:
+    return {
+        "Authorization": f"Bearer {reveal_secret(token)}",
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": API_VERSION,
+    }
+
+
+def github_url(path: str, **kwargs: str) -> str:
+    return API_BASE + path.format(**kwargs)
+
+
+async def github_get(token: str,
+                     path: PathSpec,
+                     params: dict | None = None,
+                     **kwargs: str) -> dict:
+    url = github_url(path, **kwargs)
+    headers = github_headers(token)
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url, headers=headers, params=params) as resp:
+            resp.raise_for_status()
+            return await resp.json()
+
+
+def github_get_sync(token: str,
+                    path: PathSpec,
+                    params: dict | None = None,
+                    **kwargs: str) -> dict:
+    url = github_url(path, **kwargs)
+    if params:
+        url = f"{url}?{urlencode(params)}"
+    req = Request(url, headers=github_headers(token), method="GET")
+    with urlopen(req) as resp:
+        return json.loads(resp.read())

python/mirage/core/github/config.py

@@ -0,0 +1,22 @@
+# ========= 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 pydantic import BaseModel, SecretStr
+
+
+class GitHubConfig(BaseModel):
+    token: SecretStr
+    owner: str | None = None
+    repo: str | None = None
+    ref: str = "main"

python/mirage/core/github/constants.py

@@ -0,0 +1,16 @@
+# ========= 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. =========
+
+SCOPE_WARN = 100
+SCOPE_ERROR = 5000

python/mirage/core/github/find.py

@@ -0,0 +1,104 @@
+# ========= 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.accessor.github import GitHubAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.commands.builtin.find_eval import (FindEntry, PredNode, build_tree,
+                                               emit_start_path, keep,
+                                               start_basename)
+from mirage.types import PathSpec
+
+
+async def find(
+    accessor: GitHubAccessor,
+    path: PathSpec,
+    name: str | None = None,
+    type: str | None = None,
+    min_size: int | None = None,
+    max_size: int | None = None,
+    maxdepth: int | None = None,
+    name_exclude: str | None = None,
+    or_names: list[str] | None = None,
+    mtime_min: float | None = None,
+    mtime_max: float | None = None,
+    iname: str | None = None,
+    mindepth: int | None = None,
+    path_pattern: str | None = None,
+    empty: bool = False,
+    tree: PredNode | None = None,
+    index: IndexCacheStore = None,
+) -> list[str]:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    if index is None:
+        raise ValueError("find: no tree loaded")
+    base = path.mount_path.strip("/")
+    base_depth = 0 if base == "" else base.count("/") + 1
+    start_name = start_basename(path)
+    results: list[str] = []
+    tree = tree if tree is not None else build_tree(name=name,
+                                                    iname=iname,
+                                                    path_pattern=path_pattern,
+                                                    type=type,
+                                                    name_exclude=name_exclude,
+                                                    or_names=or_names)
+    start_kind = "d" if base == "" else None
+    start_size = 0
+    has_child = False
+    for entry_path in sorted(index._entries):
+        p = entry_path.lstrip("/")
+        if p == base:
+            meta = index._entries[entry_path]
+            start_kind = "d" if meta.resource_type == "folder" else "f"
+            start_size = meta.size or 0
+            continue
+        if base and not p.startswith(base + "/"):
+            continue
+        has_child = True
+        entry_meta = index._entries[entry_path]
+        is_dir = entry_meta.resource_type == "folder"
+        full_path = "/" + p
+        depth = p.count("/") + 1 - base_depth
+        if maxdepth is not None and depth > maxdepth:
+            continue
+        entry = FindEntry(key=full_path,
+                          name=p.rsplit("/", 1)[-1],
+                          kind="d" if is_dir else "f",
+                          depth=depth)
+        if not keep(entry, tree, mindepth):
+            continue
+        # Directories count as size 0 for -size (deliberate GNU divergence).
+        size = 0 if is_dir else (entry_meta.size or 0)
+        if min_size is not None and size < min_size:
+            continue
+        if max_size is not None and size > max_size:
+            continue
+        results.append(full_path)
+    if start_kind is not None or has_child:
+        root_kind = start_kind or "d"
+        emit_start_path(results,
+                        "/" + base if base else "/",
+                        start_name,
+                        kind=root_kind,
+                        is_empty=None,
+                        exists=True,
+                        tree=tree,
+                        maxdepth=maxdepth,
+                        mindepth=mindepth,
+                        size=start_size if root_kind == "f" else None,
+                        min_size=min_size,
+                        max_size=max_size)
+    return sorted(results)

python/mirage/core/github/glob.py

@@ -0,0 +1,29 @@
+# ========= 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.accessor.github import GitHubAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.commands.builtin.constants import SCOPE_ERROR
+from mirage.core.github.readdir import readdir
+from mirage.types import PathSpec
+from mirage.utils.glob_walk import resolve_glob_with
+
+
+async def resolve_glob(
+    accessor: GitHubAccessor,
+    paths: list[PathSpec],
+    index: IndexCacheStore,
+) -> list[PathSpec]:
+    return await resolve_glob_with(readdir, accessor, paths, index,
+                                   SCOPE_ERROR)

python/mirage/core/github/read.py

@@ -0,0 +1,59 @@
+# ========= 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 base64
+
+from mirage.accessor.github import GitHubAccessor
+from mirage.cache.index import IndexCacheStore, LookupStatus
+from mirage.core.github._client import github_get
+from mirage.core.github.config import GitHubConfig
+from mirage.types import PathSpec
+from mirage.utils.errors import enoent
+
+
+async def read_bytes(config: GitHubConfig, owner: str, repo: str,
+                     sha: str) -> bytes:
+    data = await github_get(
+        config.token,
+        "/repos/{owner}/{repo}/git/blobs/{sha}",
+        owner=owner,
+        repo=repo,
+        sha=sha,
+    )
+    return base64.b64decode(data["content"])
+
+
+async def read(
+    accessor: GitHubAccessor,
+    path: PathSpec,
+    index: IndexCacheStore = None,
+) -> bytes:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    virtual = path.virtual
+    if isinstance(path, PathSpec):
+        path = path.mount_path
+
+    key = "/" + path.strip("/")
+    if index is None:
+        raise enoent(virtual)
+    result = await index.get(key)
+    if result.status == LookupStatus.NOT_FOUND or result.entry is None:
+        raise enoent(virtual)
+    if result.entry.resource_type == "folder":
+        raise IsADirectoryError(virtual)
+    return await read_bytes(accessor.config, accessor.owner, accessor.repo,
+                            result.entry.id)

python/mirage/core/github/readdir.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. =========
+
+import logging
+
+from mirage.cache.index import IndexCacheStore, IndexEntry, LookupStatus
+from mirage.core.github.tree import fetch_dir_tree
+from mirage.types import PathSpec
+from mirage.utils.errors import enoent
+from mirage.utils.key_prefix import mount_prefix_of
+
+log = logging.getLogger(__name__)
+
+
+async def readdir(accessor, path: PathSpec,
+                  index: IndexCacheStore) -> list[str]:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    virtual = path.virtual
+    if isinstance(path, PathSpec):
+        prefix = mount_prefix_of(path.virtual, path.resource_path)
+        path = path.directory if path.pattern else path.virtual
+    if prefix and path.startswith(prefix):
+        rest = path[len(prefix):]
+        if prefix.endswith("/") or rest == "" or rest.startswith("/"):
+            path = rest or "/"
+    path = path.rstrip("/") or "/"
+    listing = await index.list_dir(path)
+    if listing.entries is not None:
+        if prefix and listing.entries and not listing.entries[0].startswith(
+                prefix):
+            return [prefix + e for e in listing.entries]
+        return listing.entries
+    if listing.status == LookupStatus.NOT_FOUND:
+        if accessor.truncated:
+            return await _fallback_readdir(accessor, path, index, virtual,
+                                           prefix)
+        raise enoent(virtual)
+    return []
+
+
+async def _fallback_readdir(
+    accessor,
+    path: str,
+    index: IndexCacheStore,
+    virtual: str,
+    prefix: str = "",
+) -> list[str]:
+    """Per-directory tree fetch when recursive tree was truncated."""
+    parent_sha = await _resolve_dir_sha(accessor, path, index)
+    if parent_sha is None:
+        raise enoent(virtual)
+    entries = await fetch_dir_tree(accessor.config, accessor.owner,
+                                   accessor.repo, parent_sha)
+    norm = "/" + path.strip("/")
+    child_keys: list[str] = []
+    for entry in entries:
+        child_path = norm + "/" + entry.path
+        resource_type = "folder" if entry.type == "tree" else "file"
+        idx_entry = IndexEntry(
+            id=entry.sha,
+            name=entry.path,
+            resource_type=resource_type,
+            size=entry.size,
+        )
+        index._entries[child_path] = idx_entry
+        child_keys.append(child_path)
+    index._children[norm] = sorted(child_keys)
+    log.debug("fallback readdir populated %d entries for %s", len(entries),
+              path)
+    virtual_keys = sorted((prefix + k if prefix else k) for k in child_keys)
+    return virtual_keys
+
+
+async def _resolve_dir_sha(accessor, path: str,
+                           index: IndexCacheStore) -> str | None:
+    """Get the tree SHA for a directory path.
+
+    Walks from root if needed, fetching per-directory trees.
+    """
+    norm = "/" + path.strip("/")
+    result = await index.get(norm)
+    if result.entry is not None:
+        return result.entry.id
+    parts = norm.strip("/").split("/")
+    current_sha = accessor.ref
+    current_path = ""
+    for part in parts:
+        entries = await fetch_dir_tree(accessor.config, accessor.owner,
+                                       accessor.repo, current_sha)
+        found = False
+        for entry in entries:
+            if entry.path == part:
+                current_sha = entry.sha
+                current_path += "/" + part
+                idx_entry = IndexEntry(
+                    id=entry.sha,
+                    name=entry.path,
+                    resource_type="folder" if entry.type == "tree" else "file",
+                    size=entry.size,
+                )
+                index._entries[current_path] = idx_entry
+                found = True
+                break
+        if not found:
+            return None
+    return current_sha

python/mirage/core/github/repo.py

@@ -0,0 +1,34 @@
+# ========= 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.core.github._client import github_get, github_get_sync
+from mirage.core.github.config import GitHubConfig
+
+
+async def fetch_default_branch(config: GitHubConfig, owner: str,
+                               repo: str) -> str:
+    data = await github_get(config.token,
+                            "/repos/{owner}/{repo}",
+                            owner=owner,
+                            repo=repo)
+    return data["default_branch"]
+
+
+def fetch_default_branch_sync(config: GitHubConfig, owner: str,
+                              repo: str) -> str:
+    data = github_get_sync(config.token,
+                           "/repos/{owner}/{repo}",
+                           owner=owner,
+                           repo=repo)
+    return data["default_branch"]

python/mirage/core/github/scope.py

@@ -0,0 +1,79 @@
+# ========= 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.cache.index import IndexEntry
+from mirage.types import PathSpec
+from mirage.utils.key_prefix import mount_prefix_of
+
+
+def scope_relative_key(path: PathSpec | str) -> str:
+    """Strip the mount prefix from a path to get its repo-relative key.
+
+    Args:
+        path (PathSpec | str): Scope path, possibly mount-prefixed.
+
+    Returns:
+        str: Repo-relative key with a leading slash; ``/`` for the root.
+    """
+    prefix = mount_prefix_of(path.virtual, path.resource_path) if isinstance(
+        path, PathSpec) else ""
+    key = path.virtual if isinstance(path, PathSpec) else str(path)
+    if prefix and key.startswith(prefix):
+        key = key[len(prefix):] or "/"
+    return key
+
+
+def is_repo_root(key: str) -> bool:
+    """Return whether a repo-relative key points at the repository root.
+
+    Args:
+        key (str): Repo-relative key from :func:`scope_relative_key`.
+
+    Returns:
+        bool: True for ``""`` or ``"/"``.
+    """
+    return key in ("", "/")
+
+
+def count_scope_files(entries: dict[str, IndexEntry], key: str) -> int:
+    """Count indexed files under a repo-relative scope key.
+
+    Args:
+        entries (dict[str, IndexEntry]): Index entries keyed by repo-relative
+            path with a leading slash.
+        key (str): Repo-relative scope key from :func:`scope_relative_key`.
+
+    Returns:
+        int: Number of file entries at or below the scope.
+    """
+    if is_repo_root(key):
+        return sum(1 for e in entries.values() if e.resource_type == "file")
+    norm = "/" + key.strip("/")
+    prefix = norm + "/"
+    return sum(
+        1 for p, e in entries.items()
+        if e.resource_type == "file" and (p == norm or p.startswith(prefix)))
+
+
+def should_use_search(
+    recursive: bool,
+    on_default_branch: bool,
+) -> bool:
+    """Whether grep/rg should narrow paths via GitHub code search.
+
+    Search only helps recursive scans on the default branch (code search only
+    indexes the default branch). Whether a usable literal exists, and whether
+    the scope is large enough to bother, is decided by the caller.
+    """
+    return recursive and on_default_branch

python/mirage/core/github/search.py

@@ -0,0 +1,99 @@
+# ========= 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 logging
+from dataclasses import dataclass
+
+from mirage.core.github._client import github_get
+from mirage.core.github.config import GitHubConfig
+from mirage.core.github.scope import scope_relative_key
+from mirage.types import PathSpec
+from mirage.utils.key_prefix import mount_key, mount_prefix_of
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SearchResult:
+    path: str
+    sha: str
+
+
+async def search_code(
+    config: GitHubConfig,
+    owner: str,
+    repo: str,
+    query: str,
+    path_filter: str | None = None,
+) -> list[SearchResult]:
+    q = f"{query} repo:{owner}/{repo}"
+    if path_filter:
+        q += f" path:{path_filter}"
+    data = await github_get(config.token, "/search/code", params={"q": q})
+    return [
+        SearchResult(path=item["path"], sha=item["sha"])
+        for item in data.get("items", [])
+    ]
+
+
+async def narrow_paths(
+    config: GitHubConfig,
+    owner: str,
+    repo: str,
+    pattern: str,
+    paths: list[PathSpec],
+) -> list[PathSpec]:
+    """Use GitHub code search to narrow paths for grep/rg.
+
+    Args:
+        config (GitHubConfig): GitHub API config.
+        owner (str): Repository owner.
+        repo (str): Repository name.
+        pattern (str): Literal search pattern.
+        paths (list[PathSpec]): Scope paths, possibly mount-prefixed.
+
+    Returns:
+        list[PathSpec]: One PathSpec per matching file, repo-relative with a
+        leading slash and the original mount prefix. Empty when search
+        returned nothing.
+    """
+    mount_prefix = (mount_prefix_of(paths[0].virtual, paths[0].resource_path)
+                    if paths and isinstance(paths[0], PathSpec) else "")
+    narrowed: list[str] = []
+    for p in paths:
+        path_filter = scope_relative_key(p).strip("/")
+        try:
+            results = await search_code(
+                config,
+                owner,
+                repo,
+                query=pattern,
+                path_filter=path_filter or None,
+            )
+        except Exception as exc:
+            logger.warning(
+                "github code search failed (%s); "
+                "falling back to per-file scan", exc)
+            continue
+        scope_prefix = path_filter + "/" if path_filter else ""
+        narrowed.extend(
+            r.path for r in results
+            if r.path == path_filter or r.path.startswith(scope_prefix))
+    return [
+        PathSpec(virtual=mount_prefix + "/" + n.lstrip("/"),
+                 directory="",
+                 resource_path=mount_key(mount_prefix + "/" + n.lstrip("/"),
+                                         mount_prefix),
+                 resolved=True) for n in narrowed
+    ]

python/mirage/core/github/stat.py

@@ -0,0 +1,69 @@
+# ========= 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.cache.index import IndexCacheStore
+from mirage.core.github.readdir import readdir as _readdir
+from mirage.types import FileStat, FileType, PathSpec
+from mirage.utils.errors import enoent
+from mirage.utils.filetype import guess_type
+from mirage.utils.key_prefix import mount_key, mount_prefix_of
+
+
+async def stat(accessor, path: PathSpec, index: IndexCacheStore) -> FileStat:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    virtual = path.virtual
+    if isinstance(path, PathSpec):
+        prefix = mount_prefix_of(path.virtual, path.resource_path)
+        path = path.virtual
+
+    if prefix and path.startswith(prefix):
+        rest = path[len(prefix):]
+        if prefix.endswith("/") or rest == "" or rest.startswith("/"):
+            path = rest or "/"
+    if path == "/" or path == "":
+        return FileStat(name="/", type=FileType.DIRECTORY)
+    key = "/" + path.strip("/") if path.strip("/") else "/"
+    result = await index.get(key)
+    if result.entry is None:
+        parent_idx = key.rsplit("/", 1)[0] or "/"
+        parent_path = (prefix + parent_idx) if prefix else parent_idx
+        try:
+            await _readdir(
+                accessor,
+                PathSpec(virtual=parent_path,
+                         directory=parent_path,
+                         resource_path=mount_key(parent_path, prefix)),
+                index=index,
+            )
+        # best-effort cache populate; canonical ENOENT raised below
+        except Exception:
+            pass
+        result = await index.get(key)
+    if result.entry is not None:
+        if result.entry.resource_type == "folder":
+            return FileStat(
+                name=result.entry.name,
+                type=FileType.DIRECTORY,
+            )
+        return FileStat(
+            name=result.entry.name,
+            size=result.entry.size,
+            type=guess_type(result.entry.name),
+            fingerprint=result.entry.id,
+            extra={"sha": result.entry.id},
+        )
+    raise enoent(virtual)

python/mirage/core/github/tree.py

@@ -0,0 +1,117 @@
+# ========= 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 logging
+
+from mirage.core.github._client import github_get, github_get_sync
+from mirage.core.github.config import GitHubConfig
+from mirage.core.github.tree_entry import TreeEntry
+
+log = logging.getLogger(__name__)
+
+
+def _parse_tree_response(
+    data: dict,
+    owner: str,
+    repo: str,
+    ref: str,
+) -> tuple[dict[str, TreeEntry], bool]:
+    truncated = bool(data.get("truncated"))
+    if truncated:
+        log.warning("GitHub tree response truncated for %s/%s@%s", owner, repo,
+                    ref)
+    result: dict[str, TreeEntry] = {}
+    for item in data.get("tree", []):
+        result[item["path"]] = TreeEntry(
+            path=item["path"],
+            type=item["type"],
+            sha=item["sha"],
+            size=item.get("size"),
+        )
+    return result, truncated
+
+
+async def fetch_tree(
+    config: GitHubConfig,
+    owner: str,
+    repo: str,
+    ref: str,
+) -> tuple[dict[str, TreeEntry], bool]:
+    """Fetch full recursive tree.
+
+    Args:
+        config (GitHubConfig): Auth + base config.
+        owner (str): Repo owner.
+        repo (str): Repo name.
+        ref (str): Branch or sha.
+
+    Returns:
+        tuple: (tree_dict, truncated) where truncated is True when
+            the repo has >100K entries and the API response is incomplete.
+    """
+    data = await github_get(
+        config.token,
+        "/repos/{owner}/{repo}/git/trees/{ref}",
+        owner=owner,
+        repo=repo,
+        ref=ref,
+        params={"recursive": "1"},
+    )
+    return _parse_tree_response(data, owner, repo, ref)
+
+
+def fetch_tree_sync(
+    config: GitHubConfig,
+    owner: str,
+    repo: str,
+    ref: str,
+) -> tuple[dict[str, TreeEntry], bool]:
+    data = github_get_sync(
+        config.token,
+        "/repos/{owner}/{repo}/git/trees/{ref}",
+        owner=owner,
+        repo=repo,
+        ref=ref,
+        params={"recursive": "1"},
+    )
+    return _parse_tree_response(data, owner, repo, ref)
+
+
+async def fetch_dir_tree(
+    config: GitHubConfig,
+    owner: str,
+    repo: str,
+    tree_sha: str,
+) -> list[TreeEntry]:
+    """Fetch a single directory's tree (non-recursive).
+
+    Used as fallback when the recursive tree was truncated.
+    """
+    data = await github_get(
+        config.token,
+        "/repos/{owner}/{repo}/git/trees/{tree_sha}",
+        owner=owner,
+        repo=repo,
+        tree_sha=tree_sha,
+    )
+    result: list[TreeEntry] = []
+    for item in data.get("tree", []):
+        result.append(
+            TreeEntry(
+                path=item["path"],
+                type=item["type"],
+                sha=item["sha"],
+                size=item.get("size"),
+            ))
+    return result

python/mirage/core/github/tree_entry.py

@@ -0,0 +1,23 @@
+# ========= 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 dataclasses import dataclass
+
+
+@dataclass
+class TreeEntry:
+    path: str
+    type: str
+    sha: str
+    size: int | None