chore: import upstream snapshot with attribution

examples/python/gmail/gmail.py

@@ -0,0 +1,264 @@
+# ========= 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 asyncio
+import json
+import os
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.gmail import GmailConfig, GmailResource
+
+load_dotenv(".env.development")
+
+config = GmailConfig(
+    client_id=os.environ["GOOGLE_CLIENT_ID"],
+    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
+    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
+)
+resource = GmailResource(config=config)
+
+
+async def main() -> None:
+    ws = Workspace({"/gmail": resource}, mode=MountMode.WRITE)
+
+    print("=== not-found errors show the full virtual path ===")
+    for cmd in ("cat /gmail/__nf_missing__.txt",
+                "head /gmail/__nf_missing__.txt",
+                "stat /gmail/__nf_missing__.txt"):
+        result = await ws.execute(cmd)
+        print(f"$ {cmd}")
+        print(f"  exit={result.exit_code}  "
+              f"{(await result.stderr_str()).strip()}")
+
+    # ls root labels
+    print("=== ls /gmail/ ===")
+    result = await ws.execute("ls /gmail/")
+    print(await result.stdout_str())
+
+    # Pick INBOX
+    labels = (await result.stdout_str()).strip().splitlines()
+    label = "INBOX"
+    if not any("INBOX" in lb for lb in labels):
+        label = labels[0] if labels else ""
+    if not label:
+        print("No labels")
+        return
+
+    # ls label (date directories)
+    print(f"=== ls /gmail/{label}/ ===")
+    result = await ws.execute(f"ls /gmail/{label}/")
+    print(await result.stdout_str())
+
+    dates = (await result.stdout_str()).strip().splitlines()
+    if not dates:
+        print("No dates")
+        return
+    first_date = dates[0]
+
+    # ls date dir (messages)
+    print(f"=== ls /gmail/{label}/{first_date}/ ===")
+    result = await ws.execute(f"ls /gmail/{label}/{first_date}/")
+    print(await result.stdout_str())
+
+    messages = [
+        m for m in (await result.stdout_str()).strip().splitlines()
+        if m.endswith(".gmail.json")
+    ]
+    if not messages:
+        print("No messages")
+        return
+    first_msg = messages[0]
+    msg_path = f"/gmail/{label}/{first_date}/{first_msg}"
+
+    # cat message
+    print(f"=== cat {msg_path} ===")
+    result = await ws.execute(f"cat {msg_path}")
+    print((await result.stdout_str())[:500])
+
+    # head
+    print("=== head -n 5 ===")
+    result = await ws.execute(f"head -n 5 {msg_path}")
+    print(await result.stdout_str())
+
+    # tail
+    print("=== tail -n 3 ===")
+    result = await ws.execute(f"tail -n 3 {msg_path}")
+    print(await result.stdout_str())
+
+    # wc
+    print("=== wc -l ===")
+    result = await ws.execute(f"wc -l {msg_path}")
+    print(await result.stdout_str())
+
+    # stat
+    print("=== stat ===")
+    result = await ws.execute(f"stat {msg_path}")
+    print(await result.stdout_str())
+
+    # jq
+    print("=== jq .subject ===")
+    result = await ws.execute(f'jq ".subject" {msg_path}')
+    print(await result.stdout_str())
+
+    print("=== jq .from ===")
+    result = await ws.execute(f'jq ".from" {msg_path}')
+    print(await result.stdout_str())
+
+    # nl
+    print("=== nl ===")
+    result = await ws.execute(f"nl {msg_path}")
+    print((await result.stdout_str())[:300])
+
+    # tree
+    print("=== tree -L 1 /gmail/ ===")
+    result = await ws.execute("tree -L 1 /gmail/")
+    print(await result.stdout_str())
+
+    print(f"=== tree -L 1 /gmail/{label}/ ===")
+    result = await ws.execute(f"tree -L 1 /gmail/{label}/")
+    print(await result.stdout_str())
+
+    # find
+    print("=== find -name '*.gmail.json' ===")
+    result = await ws.execute(
+        f'find /gmail/{label}/{first_date}/ -name "*.gmail.json" | head -n 5')
+    print(await result.stdout_str())
+
+    # grep
+    print("=== grep subject ===")
+    result = await ws.execute(f"grep subject {msg_path}")
+    print(await result.stdout_str())
+
+    # rg
+    print("=== rg subject ===")
+    result = await ws.execute(f"rg subject {msg_path}")
+    print(await result.stdout_str())
+
+    # ── native search dispatch (Gmail q= API) ────────
+    print(f"\n=== grep harbor /gmail/{label}/{first_date}/*.gmail.json"
+          " (date scope) ===")
+    result = await ws.execute(
+        f'grep harbor /gmail/{label}/{first_date}/*.gmail.json')
+    out = (await result.stdout_str()).strip()
+    lines = out.splitlines() if out else []
+    print(f"  exit={result.exit_code} matches: {len(lines)}")
+    for line in lines[:3]:
+        print(f"  {line[:150]}")
+
+    print(f"\n=== grep harbor /gmail/{label}/ (label scope) ===")
+    result = await ws.execute(f'grep harbor /gmail/{label}/')
+    out = (await result.stdout_str()).strip()
+    lines = out.splitlines() if out else []
+    print(f"  exit={result.exit_code} matches: {len(lines)}")
+    for line in lines[:3]:
+        print(f"  {line[:150]}")
+
+    print("\n=== grep harbor /gmail/ (mailbox scope) ===")
+    result = await ws.execute('grep harbor /gmail/')
+    out = (await result.stdout_str()).strip()
+    lines = out.splitlines() if out else []
+    print(f"  exit={result.exit_code} matches: {len(lines)}")
+    for line in lines[:3]:
+        print(f"  {line[:150]}")
+
+    print("\n=== rg harbor /gmail/ ===")
+    result = await ws.execute('rg harbor /gmail/')
+    out = (await result.stdout_str()).strip()
+    lines = out.splitlines() if out else []
+    print(f"  exit={result.exit_code} matches: {len(lines)}")
+    for line in lines[:3]:
+        print(f"  {line[:150]}")
+
+    # basename
+    print("=== basename ===")
+    result = await ws.execute(f"basename {msg_path}")
+    print(await result.stdout_str())
+
+    # dirname
+    print("=== dirname ===")
+    result = await ws.execute(f"dirname {msg_path}")
+    print(await result.stdout_str())
+
+    # realpath
+    print("=== realpath ===")
+    result = await ws.execute(f"realpath {msg_path}")
+    print(await result.stdout_str())
+
+    # Resource-specific commands
+
+    # gws-gmail-triage
+    print("=== gws-gmail-triage ===")
+    result = await ws.execute('gws-gmail-triage --query "is:unread" --max 3')
+    print((await result.stdout_str())[:500])
+
+    # ── glob expansion (exercises resolve_glob → readdir)
+    print("=== echo glob: *.gmail.json ===")
+    result = await ws.execute(f'echo /gmail/{label}/{first_date}/*.gmail.json')
+    out = (await result.stdout_str()).strip()
+    print(f"  {out[:200]}")
+    assert out, "glob should match at least one file"
+
+    print("=== for f in *.gmail.json (glob loop) ===")
+    result = await ws.execute(
+        f'for f in /gmail/{label}/{first_date}/*.gmail.json;'
+        ' do echo found:$f; done | head -n 3')
+    out = (await result.stdout_str()).strip()
+    for line in out.splitlines():
+        print(f"  {line[:120]}")
+
+    # gws-gmail-read (use message_id from filename)
+    msg_id = first_msg.rsplit("__", 1)[-1].replace(".gmail.json", "")
+    print(f"=== gws-gmail-read --id {msg_id} ===")
+    result = await ws.execute(f"gws-gmail-read --id {msg_id}")
+    print((await result.stdout_str())[:500])
+
+    # gws-gmail-send
+    print("=== gws-gmail-send ===")
+    result = await ws.execute('gws-gmail-send --to "zechengzhang97@gmail.com"'
+                              ' --subject "Test from MIRAGE"'
+                              ' --body "Sent by gmail.py example"')
+    out = await result.stdout_str()
+    print(out[:200])
+
+    sent_id = ""
+    if out.strip():
+        sent = json.loads(out)
+        sent_id = sent.get("id", "")
+
+    # gws-gmail-reply
+    if sent_id:
+        print("=== gws-gmail-reply ===")
+        result = await ws.execute(f'gws-gmail-reply --message-id {sent_id}'
+                                  ' --body "Reply from MIRAGE"')
+        print((await result.stdout_str())[:200])
+
+    # gws-gmail-reply-all
+    if sent_id:
+        print("=== gws-gmail-reply-all ===")
+        result = await ws.execute(f'gws-gmail-reply-all --message-id {sent_id}'
+                                  ' --body "Reply-all from MIRAGE"')
+        print((await result.stdout_str())[:200])
+
+    # gws-gmail-forward
+    if sent_id:
+        print("=== gws-gmail-forward ===")
+        result = await ws.execute(f'gws-gmail-forward --message-id {sent_id}'
+                                  ' --to "zechengzhang97@gmail.com"')
+        print((await result.stdout_str())[:200])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/gmail/gmail_fuse.py

@@ -0,0 +1,77 @@
+# ========= 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 os
+
+from dotenv import load_dotenv
+
+from mirage import Mount, MountMode, Workspace
+from mirage.resource.gmail import GmailConfig, GmailResource
+
+load_dotenv(".env.development")
+
+config = GmailConfig(
+    client_id=os.environ["GOOGLE_CLIENT_ID"],
+    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
+    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
+)
+resource = GmailResource(config=config)
+
+with Workspace({"/gmail/": Mount(resource, mode=MountMode.READ,
+                                 fuse=True)}) as ws:
+    mp = ws.fuse_mountpoint
+
+    print(f"=== FUSE MODE: mounted at {mp} ===\n")
+
+    print("--- os.listdir() labels ---")
+    labels = os.listdir(mp)
+    for lb in labels:
+        print(f"  {lb}")
+
+    inbox_path = f"{mp}/INBOX"
+    if os.path.isdir(inbox_path):
+        print("\n--- os.listdir() INBOX (dates) ---")
+        dates = os.listdir(inbox_path)
+        for d in dates[:5]:
+            print(f"  {d}")
+
+        if dates:
+            date_path = f"{inbox_path}/{dates[0]}"
+            print(f"\n--- os.listdir() {dates[0]} ---")
+            messages = os.listdir(date_path)
+            for m in messages[:5]:
+                print(f"  {m}")
+
+            json_msgs = [m for m in messages if m.endswith(".gmail.json")]
+            if json_msgs:
+                first = json_msgs[0]
+                path = f"{date_path}/{first}"
+                print(f"\n--- open() + read {first[:60]} ---")
+                with open(path) as f:
+                    content = f.read()
+                parsed = json.loads(content)
+                print(f"  subject: {parsed.get('subject', 'N/A')}")
+                print(f"  from: {parsed.get('from', 'N/A')}")
+
+    print(f"\n>>> FUSE mounted at: {mp}")
+    print(">>> Open another terminal and run:")
+    print(f">>>   ls {mp}/")
+    print(f">>>   ls {mp}/INBOX/")
+    print(">>> Press Enter to unmount and exit...")
+    input()
+
+    records = ws.ops.records
+    total = sum(r.bytes for r in records)
+    print(f"\nStats: {len(records)} ops, {total} bytes transferred")

examples/python/gmail/gmail_vfs.py

@@ -0,0 +1,83 @@
+# ========= 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 asyncio
+import json
+import os
+import sys
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.gmail import GmailConfig, GmailResource
+
+load_dotenv(".env.development")
+
+config = GmailConfig(
+    client_id=os.environ["GOOGLE_CLIENT_ID"],
+    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
+    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
+)
+resource = GmailResource(config=config)
+
+
+async def main():
+    with Workspace({"/gmail/": resource}, mode=MountMode.READ) as ws:
+        vos = sys.modules["os"]
+        print("=== VFS MODE ===\n")
+
+        print("--- os.listdir() labels ---")
+        labels = vos.listdir("/gmail")
+        for label in labels:
+            print(f"  {label}")
+
+        print("\n--- os.listdir() INBOX dates ---")
+        dates = vos.listdir("/gmail/INBOX")
+        for d in dates[:5]:
+            print(f"  {d}")
+
+        if dates:
+            first_date = dates[0]
+            print(f"\n--- os.listdir() {first_date} messages ---")
+            messages = vos.listdir(f"/gmail/INBOX/{first_date}")
+            for msg in messages[:5]:
+                print(f"  {msg}")
+
+            json_msgs = [m for m in messages if m.endswith(".gmail.json")]
+            if json_msgs:
+                first = json_msgs[0]
+                path = f"/gmail/INBOX/{first_date}/{first}"
+                print(f"\n--- open() + read {first} ---")
+                with open(path) as f:
+                    content = f.read()
+                    parsed = json.loads(content)
+                    print(f"  subject: {parsed.get('subject', 'N/A')}")
+                    print(f"  from: {parsed.get('from', 'N/A')}")
+
+                print("\n--- os.path.exists() ---")
+                print(f"  {first}: {vos.path.exists(path)}")
+
+        print("\n--- bash history ---")
+        with open("/.bash_history") as f:
+            for i, line in enumerate(f):
+                if i >= 6:
+                    break
+                print(f"  {line.rstrip()[:120]}")
+
+        records = ws.ops.records
+        total = sum(r.bytes for r in records)
+        print(f"\nStats: {len(records)} ops, {total} bytes transferred")
+
+
+asyncio.run(main())