chore: import upstream snapshot with attribution

python/mirage/commands/builtin/github/__init__.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. =========
+
+from functools import partial
+
+from mirage.commands.builtin.generic_bind import (CommandIO,
+                                                  make_generic_commands)
+from mirage.commands.builtin.github.du import du
+from mirage.commands.builtin.github.find import find
+from mirage.commands.builtin.github.grep import grep
+from mirage.commands.builtin.github.rg import rg
+from mirage.commands.builtin.utils.wrap import stream_from_bytes
+from mirage.core.github.read import read as _read
+from mirage.core.github.readdir import readdir as _readdir
+from mirage.core.github.stat import stat as _stat
+
+# GitHub repo files are read through the generic factory; find keeps a wrapper
+# for the "no tree loaded" guard and native tree-backed walk, grep and rg push
+# down to the GitHub code-search API, du uses du_multi (flat-list contract) and
+# GitHub is read-only, so the generic byte-mutation
+# commands are intentionally absent (no write op wired). There is no native
+# streaming read, so the stream op is synthesized from the whole-blob read.
+_GITHUB_CMD_OPS = CommandIO(
+    readdir=_readdir,
+    read_bytes=_read,
+    read_stream=partial(stream_from_bytes, _read),
+    stat=_stat,
+    is_mounted=lambda a: True,
+    local=False,
+)
+
+_GITHUB_OVERRIDES = {"du", "find", "grep", "rg"}
+
+COMMANDS = [
+    *make_generic_commands(
+        "github",
+        _GITHUB_CMD_OPS,
+        overrides=_GITHUB_OVERRIDES,
+    ),
+    du,
+    find,
+    grep,
+    rg,
+]

python/mirage/commands/builtin/github/_provision.py

@@ -0,0 +1,52 @@
+# ========= 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.provision.types import Precision, ProvisionResult
+from mirage.types import PathSpec
+
+
+async def file_read_provision(
+    accessor: GitHubAccessor,
+    index: IndexCacheStore | None,
+    paths: list[PathSpec],
+    command: str,
+) -> ProvisionResult:
+    if not paths or index is None:
+        return ProvisionResult(command=command, precision=Precision.UNKNOWN)
+    total = 0
+    ops = 0
+    for p in paths:
+        result = await index.get(p if isinstance(p, str) else p.virtual)
+        if result.entry and result.entry.size:
+            total += result.entry.size
+            ops += 1
+    return ProvisionResult(
+        command=command,
+        network_read_low=total,
+        network_read_high=total,
+        read_ops=ops,
+        precision=Precision.EXACT,
+    )
+
+
+async def metadata_provision(command: str) -> ProvisionResult:
+    return ProvisionResult(
+        command=command,
+        network_read_low=0,
+        network_read_high=0,
+        read_ops=0,
+        precision=Precision.EXACT,
+    )

python/mirage/commands/builtin/github/du.py

@@ -0,0 +1,75 @@
+# ========= 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 functools import partial
+
+from mirage.accessor.github import GitHubAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.commands.builtin.generic.du import du_multi
+from mirage.commands.builtin.github._provision import metadata_provision
+from mirage.commands.registry import command
+from mirage.commands.spec import SPECS
+from mirage.core.github.glob import resolve_glob
+from mirage.io.types import ByteSource, IOResult
+from mirage.provision.types import ProvisionResult
+from mirage.types import PathSpec
+
+
+async def _du_total(index: IndexCacheStore, path: PathSpec) -> int:
+    key = "/" + path.resource_path if path.resource_path else "/"
+    du_prefix = key.rstrip("/") + "/"
+    total = 0
+    for ep, entry in index._entries.items():
+        if (ep == key or ep.startswith(du_prefix)) and entry.size is not None:
+            total += entry.size
+    return total
+
+
+async def du_provision(
+    accessor: GitHubAccessor,
+    paths: list[PathSpec],
+    *texts: str,
+    index: IndexCacheStore = None,
+    **_extra: object,
+) -> ProvisionResult:
+    return await metadata_provision("du " + " ".join(
+        p.virtual if isinstance(p, PathSpec) else p for p in paths))
+
+
+@command("du", resource="github", spec=SPECS["du"], provision=du_provision)
+async def du(
+    accessor: GitHubAccessor,
+    paths: list[PathSpec],
+    *texts: str,
+    stdin: bytes | None = None,
+    h: bool = False,
+    s: bool = False,
+    a: bool = False,
+    max_depth: str | None = None,
+    c: bool = False,
+    index: IndexCacheStore = None,
+    **_extra: object,
+) -> tuple[ByteSource | None, IOResult]:
+    if index is None:
+        raise ValueError("du: no tree loaded")
+    paths = await resolve_glob(accessor, paths, index)
+    out = await du_multi(
+        paths,
+        compute_total=partial(_du_total, index),
+        h=h,
+        s=s,
+        a=a,
+        c=c,
+    )
+    return out, IOResult()

python/mirage/commands/builtin/github/find.py

@@ -0,0 +1,78 @@
+# ========= 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 functools import partial
+
+from mirage.accessor.github import GitHubAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.commands.builtin.generic.find import find as generic_find
+from mirage.commands.builtin.github._provision import metadata_provision
+from mirage.commands.registry import command
+from mirage.commands.spec import SPECS
+from mirage.core.github.find import find as find_core
+from mirage.core.github.glob import resolve_glob
+from mirage.io.types import ByteSource, IOResult
+from mirage.provision.types import ProvisionResult
+from mirage.types import PathSpec
+
+
+async def find_provision(
+    accessor: GitHubAccessor,
+    paths: list[PathSpec],
+    *texts: str,
+    index: IndexCacheStore = None,
+    **_extra: object,
+) -> ProvisionResult:
+    path_strs = [
+        p.virtual if isinstance(p, PathSpec) else str(p) for p in paths
+    ]
+    return await metadata_provision("find " + " ".join(path_strs))
+
+
+@command("find",
+         resource="github",
+         spec=SPECS["find"],
+         provision=find_provision)
+async def find(
+    accessor: GitHubAccessor,
+    paths: list[PathSpec],
+    *texts: str,
+    stdin: bytes | None = None,
+    name: str | None = None,
+    type: str | None = None,
+    maxdepth: str | None = None,
+    size: str | None = None,
+    mtime: str | None = None,
+    iname: str | None = None,
+    path: str | None = None,
+    mindepth: str | None = None,
+    index: IndexCacheStore = None,
+    **_extra: object,
+) -> tuple[ByteSource | None, IOResult]:
+    if index is None:
+        raise ValueError("find: no tree loaded")
+    paths = await resolve_glob(accessor, paths, index)
+    return await generic_find(paths,
+                              texts,
+                              find_core=partial(find_core,
+                                                accessor,
+                                                index=index),
+                              name=name,
+                              type=type,
+                              size=size,
+                              mtime=mtime,
+                              maxdepth=maxdepth,
+                              iname=iname,
+                              path=path,
+                              mindepth=mindepth)

python/mirage/commands/builtin/github/grep.py

@@ -0,0 +1,134 @@
+# ========= 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 collections.abc import AsyncIterator
+
+from mirage.accessor.github import GitHubAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.commands.builtin.generic.grep import grep as generic_grep
+from mirage.commands.builtin.github.narrow import (files_only_shortcircuit,
+                                                   narrow_scope)
+from mirage.commands.builtin.grep_helper import pattern_arg
+from mirage.commands.registry import command
+from mirage.commands.spec import SPECS
+from mirage.commands.spec.types import FlagView
+from mirage.core.github.constants import SCOPE_ERROR
+from mirage.core.github.read import read as github_read
+from mirage.core.github.readdir import readdir as github_readdir
+from mirage.core.github.stat import stat as github_stat
+from mirage.io.types import ByteSource, IOResult
+from mirage.provision import ProvisionResult
+from mirage.types import PathSpec
+from mirage.utils.key_prefix import mount_prefix_of
+
+
+async def _estimate_recursive(index, path: str) -> tuple[int, int]:
+    prefix = path.rstrip("/") + "/"
+    total = 0
+    ops = 0
+    for entry_path, entry in index._entries.items():
+        if entry.resource_type != "file":
+            continue
+        if not entry_path.startswith(prefix):
+            continue
+        total += entry.size or 0
+        ops += 1
+    return total, ops
+
+
+async def grep_provision(
+    accessor: GitHubAccessor,
+    paths: list[PathSpec],
+    *texts: str,
+    r: bool = False,
+    R: bool = False,
+    index: IndexCacheStore = None,
+    **_extra: object,
+) -> ProvisionResult:
+    if not paths or index is None:
+        return ProvisionResult(command="grep " + " ".join(texts))
+    recursive = r or R
+    total = 0
+    ops = 0
+    for p in paths:
+        p_prefix = mount_prefix_of(p.virtual, p.resource_path) if isinstance(
+            p, PathSpec) else ""
+        key = p.virtual if isinstance(p, PathSpec) else str(p)
+        if p_prefix and key.startswith(p_prefix):
+            key = key[len(p_prefix):] or "/"
+        result = await index.get(key)
+        if result.entry is None:
+            continue
+        if result.entry.resource_type == "folder":
+            if recursive:
+                t, o = await _estimate_recursive(index, key)
+                total += t
+                ops += o
+        else:
+            total += result.entry.size or 0
+            ops += 1
+    return ProvisionResult(
+        command=f"grep {texts[0] if texts else ''} ...",
+        network_read_low=total,
+        network_read_high=total,
+        read_ops=ops,
+    )
+
+
+@command("grep",
+         resource="github",
+         spec=SPECS["grep"],
+         provision=grep_provision)
+async def grep(
+    accessor: GitHubAccessor,
+    paths: list[PathSpec],
+    *texts: str,
+    stdin: AsyncIterator[bytes] | bytes | None = None,
+    index: IndexCacheStore = None,
+    **flags: object,
+) -> tuple[ByteSource | None, IOResult]:
+    fl = FlagView(flags, spec=SPECS["grep"])
+    pattern = pattern_arg(texts, fl)
+    recursive = fl.bool("r") or fl.bool("R")
+
+    resolved: list[PathSpec] = []
+    if paths and index is not None:
+        resolved, file_count, used_search = await narrow_scope(
+            accessor,
+            index,
+            paths,
+            pattern,
+            fixed_string=fl.bool("F"),
+            recursive=recursive,
+        )
+        if file_count > SCOPE_ERROR:
+            msg = f"grep: {file_count} files in scope, narrow the path\n"
+            return b"", IOResult(exit_code=1, stderr=msg.encode())
+        if used_search:
+            short = files_only_shortcircuit(fl, pattern, resolved, paths[0])
+            if short is not None:
+                return short
+
+    return await generic_grep(
+        resolved,
+        texts,
+        flags,
+        readdir=github_readdir,
+        stat=github_stat,
+        read_bytes=github_read,
+        read_stream=None,
+        accessor=accessor,
+        stdin=stdin,
+        index=index,
+    )

python/mirage/commands/builtin/github/narrow.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 collections.abc import Callable
+
+from mirage.accessor.github import GitHubAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.commands.builtin.constants import PatternType
+from mirage.commands.builtin.grep_helper import classify_pattern, search_query
+from mirage.commands.builtin.utils.output import format_records
+from mirage.commands.spec.types import FlagView
+from mirage.core.github.constants import SCOPE_WARN
+from mirage.core.github.glob import resolve_glob
+from mirage.core.github.scope import (count_scope_files, scope_relative_key,
+                                      should_use_search)
+from mirage.core.github.search import narrow_paths
+from mirage.io.types import ByteSource, IOResult
+from mirage.types import PathSpec
+from mirage.utils.path import rebase_raw
+
+
+async def narrow_scope(
+    accessor: GitHubAccessor,
+    index: IndexCacheStore,
+    paths: list[PathSpec],
+    pattern: str | None,
+    *,
+    fixed_string: bool,
+    recursive: bool,
+) -> tuple[list[PathSpec], int, bool]:
+    """Resolve grep/rg scope paths, narrowing via GitHub code search.
+
+    Narrows any recursive scope (repo root or subdirectory) on the default
+    branch when a literal can be pushed down to code search and the scope is
+    larger than ``SCOPE_WARN``; otherwise expands the scope by glob. Regex
+    patterns narrow on an extracted required literal and stay exact because the
+    caller still scans the regex over the narrowed files.
+
+    Args:
+        accessor (GitHubAccessor): backend handle.
+        index (IndexCacheStore): populated path/size index.
+        paths (list[PathSpec]): scope paths, possibly mount-prefixed.
+        pattern (str | None): the search pattern, or None for -f-only greps.
+        fixed_string (bool): True if -F is set.
+        recursive (bool): True if -r/-R is set.
+
+    Returns:
+        tuple[list[PathSpec], int, bool]: resolved file paths, the file count
+            in scope (narrowed count when search was used), and whether code
+            search actually narrowed the set.
+    """
+    key = scope_relative_key(paths[0])
+    file_count = count_scope_files(index._entries, key)
+    query = search_query(pattern,
+                         fixed_string) if pattern is not None else None
+    use_search = (query is not None and should_use_search(
+        recursive=recursive,
+        on_default_branch=(accessor.ref == accessor.default_branch),
+    ) and file_count > SCOPE_WARN)
+    if use_search:
+        narrowed = await narrow_paths(accessor.config, accessor.owner,
+                                      accessor.repo, query, paths)
+        if narrowed:
+            return narrowed, len(narrowed), True
+    resolved = await resolve_glob(accessor, paths, index)
+    return resolved, file_count, False
+
+
+def files_only_shortcircuit(
+    fl: FlagView,
+    pattern: str | None,
+    resolved: list[PathSpec],
+    scope: PathSpec,
+    path_predicate: Callable[[str], bool] | None = None,
+) -> tuple[ByteSource, IOResult] | None:
+    """Emit the narrowed file list for a plain literal -l without reading.
+
+    When code search has already narrowed the scope to the files containing a
+    fully literal pattern, those files are exactly the answer to ``-l``
+    (files-with-matches), so the content fetches the generic command would do
+    can be skipped entirely. Returns None whenever the short-circuit is unsafe
+    (no -l, a non-literal pattern, or a flag that changes which lines match) so
+    the caller falls back to the generic scan. ``path_predicate`` reproduces
+    any file filtering the generic command applies (rg's hidden/--type/--glob
+    rules); files it rejects are dropped, matching the generic output.
+
+    Args:
+        fl (FlagView): spec-validated view over the raw flag kwargs.
+        pattern (str | None): the search pattern.
+        resolved (list[PathSpec]): the narrowed file paths.
+        scope (PathSpec): the original scope path, for display rebasing.
+        path_predicate (Callable[[str], bool] | None): keeps only narrowed
+            paths for which it returns True; None keeps all (grep semantics).
+
+    Returns:
+        tuple[ByteSource, IOResult] | None: the formatted file list, or None.
+    """
+    if not fl.bool("args_l") or pattern is None:
+        return None
+    if (fl.bool("i") or fl.bool("w") or fl.bool("v") or fl.bool("c")
+            or fl.bool("o")):
+        return None
+    fixed = fl.bool("F")
+    pt = classify_pattern(pattern, fixed)
+    fully_literal = fixed or pt == PatternType.EXACT or (
+        pt == PatternType.SIMPLE and "." not in pattern)
+    if not fully_literal:
+        return None
+    hits = [
+        p.virtual for p in resolved
+        if path_predicate is None or path_predicate(p.virtual)
+    ]
+    if not hits:
+        return b"", IOResult(exit_code=1)
+    spelled = rebase_raw(hits, scope.virtual, scope.raw_path)
+    return format_records(sorted(spelled)), IOResult()

python/mirage/commands/builtin/github/rg.py

@@ -0,0 +1,90 @@
+# ========= 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 collections.abc import AsyncIterator
+from functools import partial
+
+from mirage.accessor.github import GitHubAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.commands.builtin.generic.rg import rg as generic_rg
+from mirage.commands.builtin.github.narrow import (files_only_shortcircuit,
+                                                   narrow_scope)
+from mirage.commands.builtin.grep_helper import pattern_arg
+from mirage.commands.builtin.rg_helper import rg_matches_filter
+from mirage.commands.errors import UsageError
+from mirage.commands.registry import command
+from mirage.commands.spec import SPECS
+from mirage.commands.spec.types import FlagView
+from mirage.core.github.constants import SCOPE_ERROR
+from mirage.core.github.read import read as github_read
+from mirage.core.github.readdir import readdir as _readdir
+from mirage.core.github.stat import stat as _stat
+from mirage.io.types import ByteSource, IOResult
+from mirage.types import PathSpec
+
+
+@command("rg", resource="github", spec=SPECS["rg"])
+async def rg(
+    accessor: GitHubAccessor,
+    paths: list[PathSpec],
+    *texts: str,
+    stdin: AsyncIterator[bytes] | bytes | None = None,
+    index: IndexCacheStore = None,
+    **flags: object,
+) -> tuple[ByteSource | None, IOResult]:
+    fl = FlagView(flags, spec=SPECS["rg"])
+    pattern_str = pattern_arg(texts, fl)
+    if pattern_str is None:
+        raise UsageError("rg: usage: rg [flags] pattern [path]")
+
+    if paths and index is None:
+        return b"", IOResult(exit_code=1)
+    if paths:
+        scope = paths[0]
+        paths, file_count, used_search = await narrow_scope(
+            accessor,
+            index,
+            paths,
+            pattern_str,
+            fixed_string=fl.bool("F"),
+            recursive=True,
+        )
+        if file_count > SCOPE_ERROR:
+            msg = f"rg: {file_count} files in scope, narrow the path\n"
+            return b"", IOResult(exit_code=1, stderr=msg.encode())
+        if used_search:
+            predicate = partial(rg_matches_filter,
+                                file_type=fl.str("type"),
+                                glob_pattern=fl.str("glob"),
+                                hidden=fl.bool("hidden"))
+            short = files_only_shortcircuit(fl,
+                                            pattern_str,
+                                            paths,
+                                            scope,
+                                            path_predicate=predicate)
+            if short is not None:
+                return short
+
+    return await generic_rg(
+        paths,
+        texts,
+        flags,
+        readdir=_readdir,
+        stat=_stat,
+        read_bytes=github_read,
+        read_stream=None,
+        accessor=accessor,
+        stdin=stdin,
+        index=index,
+    )