chore: import upstream snapshot with attribution

python/mirage/core/gdocs/__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/gdocs/_client.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.google._client import DOCS_API_BASE  # noqa: F401
+from mirage.core.google._client import (DRIVE_API_BASE, TOKEN_BUFFER_SECONDS,
+                                        TOKEN_URL, TokenManager, google_get,
+                                        google_get_bytes, google_headers,
+                                        google_post, google_put,
+                                        refresh_access_token)
+
+__all__ = [
+    "DOCS_API_BASE",
+    "DRIVE_API_BASE",
+    "TOKEN_URL",
+    "TOKEN_BUFFER_SECONDS",
+    "TokenManager",
+    "google_get",
+    "google_get_bytes",
+    "google_headers",
+    "google_post",
+    "google_put",
+    "refresh_access_token",
+]

python/mirage/core/gdocs/create.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.core.gdocs._client import DOCS_API_BASE, TokenManager, google_post
+
+
+async def create_doc(token_manager: TokenManager, title: str) -> dict:
+    """Create a new empty Google Doc with a title.
+
+    Args:
+        token_manager (TokenManager): manages OAuth2 tokens.
+        title (str): document title.
+
+    Returns:
+        dict: API response with documentId, title, etc.
+    """
+    url = f"{DOCS_API_BASE}/documents"
+    return await google_post(token_manager, url, {"title": title})

python/mirage/core/gdocs/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.gdocs import GDocsAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.commands.builtin.constants import SCOPE_ERROR
+from mirage.core.gdocs.readdir import readdir
+from mirage.types import PathSpec
+from mirage.utils.glob_walk import resolve_glob_with
+
+
+async def resolve_glob(
+    accessor: GDocsAccessor,
+    paths: list[PathSpec],
+    index: IndexCacheStore,
+) -> list[PathSpec]:
+    return await resolve_glob_with(readdir, accessor, paths, index,
+                                   SCOPE_ERROR)

python/mirage/core/gdocs/read.py

@@ -0,0 +1,63 @@
+# ========= 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
+import posixpath
+
+from mirage.accessor.gdocs import GDocsAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.core.gdocs._client import DOCS_API_BASE, TokenManager, google_get
+from mirage.core.gdocs.readdir import readdir
+from mirage.types import PathSpec
+from mirage.utils.errors import enoent
+from mirage.utils.key_prefix import mount_key, mount_prefix_of
+
+
+async def read_doc(token_manager: TokenManager, doc_id: str) -> bytes:
+    url = f"{DOCS_API_BASE}/documents/{doc_id}"
+    data = await google_get(token_manager, url)
+    return json.dumps(data, ensure_ascii=False, separators=(",", ":")).encode()
+
+
+async def read(
+    accessor: GDocsAccessor,
+    path: PathSpec,
+    index: IndexCacheStore = None,
+) -> bytes:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    virtual = path.virtual
+    prefix = mount_prefix_of(path.virtual, path.resource_path)
+    key = path.resource_path
+    if index is None:
+        raise enoent(virtual)
+    virtual_key = prefix + "/" + key if prefix else "/" + key
+    result = await index.get(virtual_key)
+    if result.entry is None:
+        parent_key = posixpath.dirname(virtual_key) or "/"
+        if parent_key != virtual_key:
+            parent_path = PathSpec.from_str_path(parent_key,
+                                                 mount_key(parent_key, prefix))
+            try:
+                await readdir(accessor, parent_path, index)
+                result = await index.get(virtual_key)
+            except Exception:
+                pass
+        if result.entry is None:
+            raise enoent(virtual)
+    if result.entry.resource_type in ("gdocs/directory", ):
+        raise IsADirectoryError(virtual)
+    return await read_doc(accessor.token_manager, result.entry.id)

python/mirage/core/gdocs/readdir.py

@@ -0,0 +1,98 @@
+# ========= 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.gdocs import GDocsAccessor
+from mirage.cache.index import IndexCacheStore, IndexEntry
+from mirage.core.google.date_glob import glob_to_modified_range
+from mirage.core.google.drive import GoogleFileSuffix, list_all_files
+from mirage.resource.gdocs.doc_entry import make_filename
+from mirage.types import PathSpec
+from mirage.utils.errors import enoent
+from mirage.utils.key_prefix import mount_prefix_of
+
+MIME = "application/vnd.google-apps.document"
+
+
+def is_dir_name(child: str) -> bool:
+    # readdir emits only folders and rendered *.gdoc.json files.
+    return not child.endswith(GoogleFileSuffix.GDOC.value)
+
+
+async def readdir(
+    accessor: GDocsAccessor,
+    path: PathSpec,
+    index: IndexCacheStore = None,
+) -> list[str]:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    virtual = path.virtual
+    modified_range = None
+    if isinstance(path, PathSpec):
+        prefix = mount_prefix_of(path.virtual, path.resource_path)
+        if path.pattern:
+            modified_range = glob_to_modified_range(path.pattern)
+        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 "/"
+    key = path.strip("/")
+    virtual_key = prefix + "/" + key if key else prefix or "/"
+
+    if not key:
+        return [f"{prefix}/owned", f"{prefix}/shared"]
+
+    if key not in ("owned", "shared"):
+        raise enoent(virtual)
+
+    if index is not None and not modified_range:
+        cached = await index.list_dir(virtual_key)
+        if cached.entries is not None:
+            return cached.entries
+
+    range_kwargs: dict[str, str] = {}
+    if modified_range:
+        range_kwargs["modified_after"] = modified_range[0]
+        range_kwargs["modified_before"] = modified_range[1]
+    files = await list_all_files(accessor.token_manager,
+                                 mime_type=MIME,
+                                 **range_kwargs)
+    is_owned = key == "owned"
+    entries = []
+    for f in files:
+        owners = f.get("owners", [])
+        first_owner = owners[0] if owners else {}
+        file_owned = first_owner.get("me", False)
+        if file_owned != is_owned:
+            continue
+        filename = make_filename(f["name"], f["id"], f.get("modifiedTime", ""))
+        entry = IndexEntry(
+            id=f["id"],
+            name=f["name"],
+            resource_type="gdocs/file",
+            remote_time=f.get("modifiedTime", ""),
+            vfs_name=filename,
+            size=int(f.get("size") or f.get("quotaBytesUsed") or 0) or None,
+        )
+        entries.append((filename, entry))
+
+    if index is not None:
+        if modified_range:
+            for name, entry in entries:
+                await index.put(f"{virtual_key}/{name}", entry)
+        else:
+            await index.set_dir(virtual_key, entries)
+    return [f"{prefix}/{key}/{name}" for name, _ in entries]

python/mirage/core/gdocs/stat.py

@@ -0,0 +1,18 @@
+# ========= 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.gdocs.readdir import readdir
+from mirage.core.google.tree_ops import make_stat
+
+stat = make_stat(readdir)

python/mirage/core/gdocs/unlink.py

@@ -0,0 +1,18 @@
+# ========= 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.gdocs.readdir import readdir
+from mirage.core.google.tree_ops import make_unlink
+
+unlink = make_unlink(readdir)

python/mirage/core/gdocs/update.py

@@ -0,0 +1,44 @@
+# ========= 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 mirage.core.gdocs._client import DOCS_API_BASE, TokenManager, google_post
+
+
+async def batch_update(
+    token_manager: TokenManager,
+    doc_id: str,
+    requests_json: str,
+) -> dict:
+    """Send batchUpdate to Google Docs API.
+
+    Args:
+        token_manager (TokenManager): manages OAuth2 tokens.
+        doc_id (str): Google Docs document ID.
+        requests_json (str): JSON string with "requests" key.
+
+    Returns:
+        dict: API response.
+    """
+    try:
+        payload = json.loads(requests_json)
+    except json.JSONDecodeError as exc:
+        raise ValueError(
+            f"Invalid JSON: {exc}. Payload must contain 'requests' key."
+        ) from exc
+    if "requests" not in payload:
+        raise ValueError("Payload must contain 'requests' key.")
+    url = f"{DOCS_API_BASE}/documents/{doc_id}:batchUpdate"
+    return await google_post(token_manager, url, payload)

python/mirage/core/gdocs/write.py

@@ -0,0 +1,44 @@
+# ========= 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.gdocs._client import DOCS_API_BASE, TokenManager, google_post
+
+
+async def append_text(
+    token_manager: TokenManager,
+    doc_id: str,
+    text: str,
+) -> dict:
+    """Append text to the end of a Google Doc.
+
+    Args:
+        token_manager (TokenManager): manages OAuth2 tokens.
+        doc_id (str): Google Docs document ID.
+        text (str): plain text to append.
+
+    Returns:
+        dict: batchUpdate API response.
+    """
+    payload = {
+        "requests": [{
+            "insertText": {
+                "text": text,
+                "endOfSegmentLocation": {
+                    "segmentId": ""
+                },
+            }
+        }]
+    }
+    url = f"{DOCS_API_BASE}/documents/{doc_id}:batchUpdate"
+    return await google_post(token_manager, url, payload)