chore: import upstream snapshot with attribution

python/mirage/resource/gdocs/__init__.py

@@ -0,0 +1,25 @@
+# ========= 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.resource.gdocs.config import GDocsConfig
+from mirage.resource.gdocs.doc_entry import DocEntry
+
+__all__ = ["GDocsConfig", "DocEntry", "GDocsResource"]
+
+
+def __getattr__(name: str):
+    if name == "GDocsResource":
+        from mirage.resource.gdocs.gdocs import GDocsResource
+        return GDocsResource
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

python/mirage/resource/gdocs/config.py

@@ -0,0 +1,19 @@
+# ========= 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.config import GoogleConfig
+
+
+class GDocsConfig(GoogleConfig):
+    pass

python/mirage/resource/gdocs/doc_entry.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. =========
+
+import re
+from dataclasses import dataclass
+
+TITLE_MAX_CHARS = 100
+UNSAFE_CHARS = re.compile(r'[^\w\s\-.]')
+MULTI_UNDERSCORE = re.compile(r'_+')
+
+
+@dataclass
+class DocEntry:
+    id: str
+    name: str
+    modified_time: str
+    created_time: str
+    owner: str | None
+    owned_by_me: bool
+    can_edit: bool
+    filename: str
+
+
+def sanitize_title(title: str) -> str:
+    """Sanitize a document title for use in filenames.
+
+    Args:
+        title (str): raw document title.
+
+    Returns:
+        str: sanitized title, max 100 chars.
+    """
+    if not title.strip():
+        return "Untitled"
+    cleaned = UNSAFE_CHARS.sub("_", title)
+    cleaned = cleaned.replace(" ", "_")
+    cleaned = MULTI_UNDERSCORE.sub("_", cleaned)
+    cleaned = cleaned.strip("_")
+    if len(cleaned) > TITLE_MAX_CHARS:
+        cleaned = cleaned[:TITLE_MAX_CHARS - 3] + "..."
+    return cleaned
+
+
+def make_filename(title: str, doc_id: str, modified_time: str = "") -> str:
+    """Build a filename from title, doc ID, and modified date.
+
+    Args:
+        title (str): raw document title.
+        doc_id (str): Google Docs document ID.
+        modified_time (str): ISO 8601 timestamp.
+
+    Returns:
+        str: filename in format "YYYY-MM-DD_Sanitized_Title__docid.json".
+    """
+    date_prefix = modified_time[:10] if len(modified_time) >= 10 else ""
+    if date_prefix:
+        return f"{date_prefix}_{sanitize_title(title)}__{doc_id}.gdoc.json"
+    return f"{sanitize_title(title)}__{doc_id}.gdoc.json"

python/mirage/resource/gdocs/gdocs.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 mirage.accessor.gdocs import GDocsAccessor
+from mirage.core.gdocs.glob import resolve_glob as _resolve_glob
+from mirage.core.google._client import TokenManager
+from mirage.resource.base import BaseResource
+from mirage.resource.gdocs.config import GDocsConfig
+from mirage.resource.gdocs.prompt import PROMPT, WRITE_PROMPT
+from mirage.types import ResourceName
+
+
+class GDocsResource(BaseResource):
+
+    name: str = ResourceName.GDOCS
+    caches_reads: bool = True
+    PROMPT: str = PROMPT
+    WRITE_PROMPT: str = WRITE_PROMPT
+
+    def __init__(self, config: GDocsConfig) -> None:
+        super().__init__()
+        self.config = config
+        self._token_manager = TokenManager(config)
+        self.accessor = GDocsAccessor(self.config, self._token_manager)
+        from mirage.commands.builtin.gdocs import COMMANDS
+        from mirage.ops.gdocs import OPS as GDOCS_VFS_OPS
+
+        for fn in COMMANDS:
+            self.register(fn)
+        for fn in GDOCS_VFS_OPS:
+            self.register_op(fn)
+
+    async def resolve_glob(self, paths, prefix: str = ""):
+        return await _resolve_glob(self.accessor, paths, index=self._index)
+
+    async def fingerprint(self, path: str) -> str | None:
+        lookup = await self._index.get(path)
+        return lookup.entry.remote_time if lookup.entry else None
+
+    def get_state(self) -> dict:
+        return self.config_state(self.config)
+
+    def load_state(self, state: dict) -> None:
+        pass

python/mirage/resource/gdocs/prompt.py

@@ -0,0 +1,84 @@
+# ========= 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. =========
+
+PROMPT = """\
+{prefix}
+  owned/
+    <date>_<title>__<doc-id>.gdoc.json
+  shared/
+    <date>_<title>__<doc-id>.gdoc.json
+
+  Filename: <YYYY-MM-DD>_<title>__<doc-id>.gdoc.json
+    <YYYY-MM-DD>  modifiedTime, used for date-glob (e.g. 2026-05-*)
+    <title>       sanitized: spaces->_, non-[A-Za-z0-9_.-]->_, <=100 chars
+    <doc-id>      Google Docs document ID
+
+  Buckets:
+    owned/   docs you created
+    shared/  docs shared with you by others
+             - does NOT include docs you own and shared with others;
+               those are still in owned/.
+
+  gdoc.json structure (matches the Google Docs API documents.get response):
+    {{
+      "documentId": "...",
+      "title": "...",
+      "body": {{
+        "content": [
+          {{                              # one element per block
+            "paragraph": {{
+              "elements": [
+                {{ "textRun": {{ "content": "the actual text\\n",
+                               "textStyle": {{...}} }} }}
+              ],
+              "paragraphStyle": {{...}}
+            }}
+          }},
+          {{ "table": {{...}} }},
+          {{ "sectionBreak": {{...}} }}
+        ]
+      }},
+      "documentStyle": {{...}},
+      "namedStyles": {{...}},
+      "revisionId": "...",
+      "suggestionsViewMode": "..."
+    }}
+
+  Useful jq paths:
+    .title
+    .body.content[].paragraph.elements[].textRun.content   # all text
+    [.body.content[] | select(.table)] | length            # table count
+    .revisionId"""
+
+WRITE_PROMPT = """\
+  Write commands:
+    gws-docs-write --document <doc-id> --text "text to append"
+
+    gws-docs-documents-create --json '{"title": "My Doc"}'
+
+    gws-docs-documents-batchUpdate \\
+      --params '{"documentId": "<id>"}' \\
+      --json   '{"requests": [{"insertText": {"location": {"index": 1}, "text": "Hello"}}]}'
+
+  Newline gotcha: bash double-quoted "...\\n..." is NOT a newline; the
+  literal characters \\ + n end up in the doc. Either:
+    --text $'line1\\nline2'                          # ANSI-C quoting
+    --text "$(printf 'line1\\nline2')"               # printf interprets
+    gws-docs-documents-batchUpdate --json '{...}'    # JSON handles escapes
+
+  Delete:
+    rm {prefix}/owned/<file>.gdoc.json      # permanent delete from Drive
+    rm -f <path>                            # ignore if missing
+    Only operates on .gdoc.json files; owned/ and shared/ themselves
+    cannot be removed."""