chore: import upstream snapshot with attribution

examples/python/github_ci/github_ci.py

@@ -0,0 +1,232 @@
+# ========= 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 os
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.github_ci import GitHubCIConfig, GitHubCIResource
+
+load_dotenv(".env.development")
+
+config = GitHubCIConfig(
+    token=os.environ["GITHUB_TOKEN"],
+    owner="strukto-ai",
+    repo="mirage",
+    max_runs=300,
+)
+resource = GitHubCIResource(config=config)
+
+
+async def main():
+    ws = Workspace({"/ci": resource}, mode=MountMode.READ)
+
+    print("=== not-found errors show the full virtual path ===")
+    for cmd in ("cat /ci/__nf_missing__.txt", "head /ci/__nf_missing__.txt",
+                "stat /ci/__nf_missing__.txt"):
+        result = await ws.execute(cmd)
+        print(f"$ {cmd}")
+        print(f"  exit={result.exit_code}  "
+              f"{(await result.stderr_str()).strip()}")
+
+    # ── discover structure ────────────────────────────
+    print("=== ls /ci/ (root) ===")
+    r = await ws.execute("ls /ci/")
+    print(await r.stdout_str())
+
+    # ── list workflows ────────────────────────────────
+    print("=== ls /ci/workflows/ ===")
+    r = await ws.execute("ls /ci/workflows/")
+    print(await r.stdout_str())
+
+    workflows = (await r.stdout_str()).strip().splitlines()
+    if not workflows or not workflows[0]:
+        print("no workflows found")
+        return
+
+    wf_name = workflows[0].strip()
+
+    # ── read workflow metadata ────────────────────────
+    print(f"=== cat /ci/workflows/{wf_name} ===")
+    r = await ws.execute(f'cat "/ci/workflows/{wf_name}"')
+    print((await r.stdout_str())[:500])
+
+    # ── list runs ─────────────────────────────────────
+    print("\n=== ls /ci/runs/ ===")
+    r = await ws.execute("ls /ci/runs/")
+    print(await r.stdout_str())
+
+    print("\n=== ls -l /ci/runs/ (mtime from updated_at) ===")
+    long_runs = await ws.execute("ls -l /ci/runs/ | head -n 5")
+    print(await long_runs.stdout_str())
+
+    runs = (await r.stdout_str()).strip().splitlines()
+    if not runs or not runs[0]:
+        print("no runs found")
+        return
+
+    run_name = runs[0].strip()
+    run_path = f"/ci/runs/{run_name}"
+
+    # ── list run contents ─────────────────────────────
+    print(f"=== ls {run_path}/ ===")
+    r = await ws.execute(f'ls "{run_path}/"')
+    print(await r.stdout_str())
+
+    # ── read run metadata ─────────────────────────────
+    print(f"=== cat {run_path}/run.json | head -n 20 ===")
+    r = await ws.execute(f'cat "{run_path}/run.json" | head -n 20')
+    print(await r.stdout_str())
+
+    # ── stat on the run ───────────────────────────────
+    print(f"=== stat {run_path} ===")
+    r = await ws.execute(f'stat "{run_path}"')
+    print(f"  {(await r.stdout_str()).strip()}")
+
+    # ── list jobs ─────────────────────────────────────
+    jobs_path = f"{run_path}/jobs"
+    print(f"\n=== ls {jobs_path}/ ===")
+    r = await ws.execute(f'ls "{jobs_path}/"')
+    print(await r.stdout_str())
+
+    jobs_out = (await r.stdout_str()).strip().splitlines()
+    json_jobs = [j.strip() for j in jobs_out if j.strip().endswith(".json")]
+    log_jobs = [j.strip() for j in jobs_out if j.strip().endswith(".log")]
+
+    # ── read a job .json ──────────────────────────────
+    if json_jobs:
+        job_name = json_jobs[0]
+        job_path = f"{jobs_path}/{job_name}"
+        print(f"=== cat {job_name} | head -n 20 ===")
+        r = await ws.execute(f'cat "{job_path}" | head -n 20')
+        print(await r.stdout_str())
+
+        print(f"=== stat {job_name} ===")
+        r = await ws.execute(f'stat "{job_path}"')
+        print(f"  {(await r.stdout_str()).strip()}")
+
+    # ── read a job .log ───────────────────────────────
+    if log_jobs:
+        log_name = log_jobs[0]
+        log_path = f"{jobs_path}/{log_name}"
+        print(f"=== head -n 20 {log_name} ===")
+        r = await ws.execute(f'head -n 20 "{log_path}"')
+        print((await r.stdout_str())[:1000])
+
+        print(f"\n=== tail -n 10 {log_name} ===")
+        r = await ws.execute(f'tail -n 10 "{log_path}"')
+        print((await r.stdout_str())[:500])
+
+        print(f"\n=== wc -l {log_name} ===")
+        r = await ws.execute(f'wc -l "{log_path}"')
+        print(f"  {(await r.stdout_str()).strip()}")
+
+    # ── annotations ───────────────────────────────────
+    print(f"\n=== cat {run_path}/annotations.jsonl ===")
+    r = await ws.execute(f'cat "{run_path}/annotations.jsonl"')
+    out = (await r.stdout_str()).strip()
+    if out:
+        for line in out.splitlines()[:5]:
+            print(f"  {line[:120]}")
+    else:
+        print("  (no annotations)")
+
+    # ── artifacts ─────────────────────────────────────
+    print(f"\n=== ls {run_path}/artifacts/ ===")
+    r = await ws.execute(f'ls "{run_path}/artifacts/"')
+    out = (await r.stdout_str()).strip()
+    if out:
+        print(out)
+    else:
+        print("  (no artifacts)")
+
+    # ── tree ──────────────────────────────────────────
+    print("\n=== tree -L 2 /ci/ ===")
+    r = await ws.execute("tree -L 2 /ci/")
+    print(await r.stdout_str())
+
+    # ── find (scoped to a single run) ─────────────────
+    print(f"=== find {run_path}/ -name '*.log' | head -n 10 ===")
+    r = await ws.execute(f'find "{run_path}/" -name "*.log" | head -n 10')
+    print(await r.stdout_str())
+
+    print(f"=== find {run_path}/ -name '*.json' | head -n 10 ===")
+    r = await ws.execute(f'find "{run_path}/" -name "*.json" | head -n 10')
+    print(await r.stdout_str())
+
+    # -path matches the display path; -size counts dirs and sizeless
+    # rendered files as 0 (so +0c drops them, -1k keeps them).
+    print(f"=== find {run_path}/ -path '*jobs*' | head -n 5 ===")
+    r = await ws.execute(f'find "{run_path}/" -path "*jobs*" | head -n 5')
+    print(await r.stdout_str())
+
+    print(f"=== find {run_path}/ -maxdepth 1 -size +0c ===")
+    r = await ws.execute(f'find "{run_path}/" -maxdepth 1 -size +0c')
+    print(f"  exit={r.exit_code} (sizeless entries count as 0,"
+          " expect no output)")
+
+    # ── cd into a run ─────────────────────────────────
+    print("=== pwd ===")
+    r = await ws.execute("pwd")
+    print(f"  {(await r.stdout_str()).strip()}")
+
+    print(f'\n=== cd "{run_path}" ===')
+    r = await ws.execute(f'cd "{run_path}"')
+    print(f"  exit={r.exit_code}")
+
+    print("\n=== pwd (after cd) ===")
+    r = await ws.execute("pwd")
+    print(f"  {(await r.stdout_str()).strip()}")
+
+    print("\n=== ls (relative, in run dir) ===")
+    r = await ws.execute("ls")
+    print(await r.stdout_str())
+
+    print("=== cat run.json | head -n 5 (relative) ===")
+    r = await ws.execute("cat run.json | head -n 5")
+    print(await r.stdout_str())
+
+    # ── cd into jobs ──────────────────────────────────
+    print('=== cd jobs ===')
+    r = await ws.execute("cd jobs")
+    print(f"  exit={r.exit_code}")
+
+    print("\n=== pwd (after cd jobs) ===")
+    r = await ws.execute("pwd")
+    print(f"  {(await r.stdout_str()).strip()}")
+
+    print("\n=== ls (relative, in jobs dir) ===")
+    r = await ws.execute("ls")
+    print(await r.stdout_str())
+
+    if log_jobs:
+        log_name = log_jobs[0]
+        print(f"=== head -n 5 {log_name} (relative) ===")
+        r = await ws.execute(f"head -n 5 {log_name}")
+        print((await r.stdout_str())[:300])
+
+    # ── stat on workflows ─────────────────────────────
+    print("\n=== stat /ci/workflows/ ===")
+    r = await ws.execute('stat "/ci/workflows/"')
+    print(f"  {(await r.stdout_str()).strip()}")
+
+    print("\n=== stat /ci/runs/ ===")
+    r = await ws.execute('stat "/ci/runs/"')
+    print(f"  {(await r.stdout_str()).strip()}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/github_ci/github_ci_fuse.py

@@ -0,0 +1,128 @@
+# ========= 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.github_ci import GitHubCIConfig, GitHubCIResource
+
+load_dotenv(".env.development")
+
+config = GitHubCIConfig(
+    token=os.environ["GITHUB_TOKEN"],
+    owner="strukto-ai",
+    repo="mirage",
+    max_runs=300,
+)
+resource = GitHubCIResource(config=config)
+
+with Workspace({"/ci/": Mount(resource, mode=MountMode.READ,
+                              fuse=True)}) as ws:
+    mp = ws.fuse_mountpoint
+
+    print(f"=== FUSE MODE: mounted at {mp} ===\n")
+
+    # ── list root ────────────────────────────────
+    print("--- os.listdir() root ---")
+    entries = os.listdir(mp)
+    for e in entries:
+        print(f"  {e}")
+
+    # ── list workflows ───────────────────────────
+    print("\n--- os.listdir() workflows ---")
+    workflows = os.listdir(f"{mp}/workflows")
+    for wf in workflows[:10]:
+        print(f"  {wf}")
+
+    if workflows:
+        wf_path = f"{mp}/workflows/{workflows[0]}"
+        print(f"\n--- open() + read {workflows[0]} ---")
+        with open(wf_path) as f:
+            data = json.loads(f.read())
+        print(f"  name: {data.get('name')}")
+        print(f"  state: {data.get('state')}")
+
+    # ── list runs ────────────────────────────────
+    print("\n--- os.listdir() runs ---")
+    runs = os.listdir(f"{mp}/runs")
+    for r in runs[:5]:
+        print(f"  {r}")
+    if len(runs) > 5:
+        print(f"  ... ({len(runs)} total)")
+
+    if runs:
+        run = runs[0]
+        run_dir = f"{mp}/runs/{run}"
+
+        # ── list run contents ────────────────────
+        print(f"\n--- os.listdir() {run} ---")
+        contents = os.listdir(run_dir)
+        for c in contents:
+            print(f"  {c}")
+
+        # ── read run.json ────────────────────────
+        run_json = f"{run_dir}/run.json"
+        if os.path.exists(run_json):
+            print("\n--- open() + read run.json ---")
+            with open(run_json) as f:
+                data = json.loads(f.read())
+            print(f"  status: {data.get('status')}")
+            print(f"  conclusion: {data.get('conclusion')}")
+            print(f"  event: {data.get('event')}")
+
+        # ── list and read jobs ───────────────────
+        jobs_dir = f"{run_dir}/jobs"
+        if os.path.isdir(jobs_dir):
+            print("\n--- os.listdir() jobs ---")
+            jobs = os.listdir(jobs_dir)
+            for j in jobs:
+                print(f"  {j}")
+
+            log_files = [j for j in jobs if j.endswith(".log")]
+            if log_files:
+                log_path = f"{jobs_dir}/{log_files[0]}"
+                print(
+                    f"\n--- open() + read {log_files[0]} (first 10 lines) ---")
+                with open(log_path) as f:
+                    for i, line in enumerate(f):
+                        if i >= 10:
+                            print("  ...")
+                            break
+                        print(f"  {line.rstrip()[:120]}")
+
+        # ── list artifacts ───────────────────────
+        artifacts_dir = f"{run_dir}/artifacts"
+        if os.path.isdir(artifacts_dir):
+            print("\n--- os.listdir() artifacts ---")
+            artifacts = os.listdir(artifacts_dir)
+            for a in artifacts:
+                print(f"  {a}")
+            if not artifacts:
+                print("  (none)")
+
+    # ── interactive ──────────────────────────────
+    print(f"\n>>> FUSE mounted at: {mp}")
+    print(">>> Open another terminal and run:")
+    print(f">>>   ls {mp}/")
+    print(f">>>   ls {mp}/runs/")
+    print(f">>>   cat {mp}/runs/<run>/run.json")
+    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")

examples/python/github_ci/github_ci_vfs.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. =========
+
+import asyncio
+import json
+import os
+import sys
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.github_ci import GitHubCIConfig, GitHubCIResource
+
+load_dotenv(".env.development")
+
+config = GitHubCIConfig(
+    token=os.environ["GITHUB_TOKEN"],
+    owner="strukto-ai",
+    repo="mirage",
+    max_runs=300,
+)
+resource = GitHubCIResource(config=config)
+
+
+async def main():
+    with Workspace({"/ci/": resource}, mode=MountMode.READ) as ws:
+        vos = sys.modules["os"]
+        print("=== VFS MODE: open() reads from GitHub CI transparently ===\n")
+
+        print("--- os.listdir() root ---")
+        entries = vos.listdir("/ci")
+        for e in entries:
+            print(f"  {e}")
+
+        print("\n--- os.listdir() workflows ---")
+        workflows = vos.listdir("/ci/workflows")
+        for wf in workflows[:10]:
+            print(f"  {wf}")
+
+        if workflows:
+            wf_path = f"/ci/workflows/{workflows[0]}"
+            print(f"\n--- open() + read {wf_path} ---")
+            with open(wf_path) as f:
+                data = json.loads(f.read())
+            print(f"  name: {data.get('name')}")
+            print(f"  path: {data.get('path')}")
+            print(f"  state: {data.get('state')}")
+
+        print("\n--- os.listdir() runs ---")
+        runs = vos.listdir("/ci/runs")
+        for r in runs[:5]:
+            print(f"  {r}")
+        if len(runs) > 5:
+            print(f"  ... ({len(runs)} total)")
+
+        if runs:
+            run_path = f"/ci/runs/{runs[0]}"
+            print(f"\n--- os.listdir() {run_path} ---")
+            contents = vos.listdir(run_path)
+            for c in contents:
+                print(f"  {c}")
+
+            if "run.json" in contents:
+                print("\n--- open() + read run.json ---")
+                with open(f"{run_path}/run.json") as f:
+                    data = json.loads(f.read())
+                print(f"  status: {data.get('status')}")
+                print(f"  conclusion: {data.get('conclusion')}")
+                print(f"  event: {data.get('event')}")
+                print(f"  branch: {data.get('head_branch')}")
+
+            if "jobs" in contents:
+                jobs_path = f"{run_path}/jobs"
+                print("\n--- os.listdir() jobs ---")
+                jobs = vos.listdir(jobs_path)
+                for j in jobs[:10]:
+                    print(f"  {j}")
+
+                json_jobs = [j for j in jobs if j.endswith(".json")]
+                log_jobs = [j for j in jobs if j.endswith(".log")]
+
+                if json_jobs:
+                    print("\n--- open() + read job .json ---")
+                    with open(f"{jobs_path}/{json_jobs[0]}") as f:
+                        data = json.loads(f.read())
+                    print(f"  name: {data.get('name')}")
+                    print(f"  status: {data.get('status')}")
+                    print(f"  conclusion: {data.get('conclusion')}")
+                    steps = data.get("steps", [])
+                    print(f"  steps: {len(steps)}")
+                    for s in steps[:3]:
+                        print(f"    {s.get('number')}. {s.get('name')}"
+                              f" -> {s.get('conclusion')}")
+
+                if log_jobs:
+                    print("\n--- open() + read job .log (first 10 lines) ---")
+                    with open(f"{jobs_path}/{log_jobs[0]}") as f:
+                        for i, line in enumerate(f):
+                            if i >= 10:
+                                print("  ...")
+                                break
+                            print(f"  {line.rstrip()[:120]}")
+
+        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())