chore: import upstream snapshot with attribution

examples/python/linear/linear.py

@@ -0,0 +1,213 @@
+# ========= 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.linear import LinearConfig, LinearResource
+
+load_dotenv(".env.development")
+
+config = LinearConfig(api_key=os.environ["LINEAR_API_KEY"])
+resource = LinearResource(config=config)
+
+
+async def main() -> None:
+    ws = Workspace({"/linear": resource}, mode=MountMode.READ)
+
+    print("=== not-found errors show the full virtual path ===")
+    for cmd in ("cat /linear/__nf_missing__.txt",
+                "head /linear/__nf_missing__.txt",
+                "stat /linear/__nf_missing__.txt"):
+        result = await ws.execute(cmd)
+        print(f"$ {cmd}")
+        print(f"  exit={result.exit_code}  "
+              f"{(await result.stderr_str()).strip()}")
+
+    print("=== ls /linear/teams/ ===")
+    result = await ws.execute("ls /linear/teams/")
+    print(await result.stdout_str())
+
+    print("=== ls -l /linear/teams/ (mtime from updatedAt) ===")
+    long_result = await ws.execute("ls -l /linear/teams/")
+    print(await long_result.stdout_str())
+
+    first_team = (await result.stdout_str()).strip().splitlines()[0] if (
+        await result.stdout_str()).strip() else ""
+    if not first_team:
+        print("No teams available")
+        return
+
+    print(f"=== cat /linear/teams/{first_team}/team.json ===")
+    result = await ws.execute(f"cat /linear/teams/{first_team}/team.json")
+    print(await result.stdout_str())
+
+    print(f"=== ls /linear/teams/{first_team}/issues/ ===")
+    issue_result = await ws.execute(f"ls /linear/teams/{first_team}/issues/")
+    print(await issue_result.stdout_str())
+
+    print(f"=== ls /linear/teams/{first_team}/projects/ ===")
+    project_result = await ws.execute(
+        f"ls /linear/teams/{first_team}/projects/")
+    print(await project_result.stdout_str())
+
+    project_names = (await project_result.stdout_str()).strip().splitlines()
+    mirage_project = next(
+        (name for name in project_names if name.startswith("Mirage__")),
+        "",
+    )
+    if mirage_project:
+        print(
+            f"=== cat /linear/teams/{first_team}/projects/{mirage_project} ==="
+        )
+        result = await ws.execute(
+            f"cat /linear/teams/{first_team}/projects/{mirage_project}")
+        print(await result.stdout_str())
+
+        project_payload = json.loads(await result.stdout_str())
+        print("=== issues in Mirage project ===")
+        for issue in project_payload.get("issues", []):
+            print(f"{issue['issue_key']}: "
+                  f"{issue['title']} "
+                  f"[{issue['state_name']}]")
+    else:
+        print("Mirage project not found in first team")
+
+    first_issue = (await
+                   issue_result.stdout_str()).strip().splitlines()[0] if (
+                       await issue_result.stdout_str()).strip() else ""
+    if not first_issue:
+        print("No issues available in first team")
+        return
+
+    issue_path = f"/linear/teams/{first_team}/issues/{first_issue}"
+
+    print("=== cat issue.json ===")
+    result = await ws.execute(f"cat {issue_path}/issue.json")
+    print(await result.stdout_str())
+
+    print("=== head -n 3 comments.jsonl ===")
+    result = await ws.execute(f"head -n 3 {issue_path}/comments.jsonl")
+    print(await result.stdout_str())
+
+    print("=== tail -n 1 comments.jsonl ===")
+    result = await ws.execute(f"tail -n 1 {issue_path}/comments.jsonl")
+    print(await result.stdout_str())
+
+    print("=== wc -l comments.jsonl ===")
+    result = await ws.execute(f"wc -l {issue_path}/comments.jsonl")
+    print(await result.stdout_str())
+
+    print("=== stat issue.json ===")
+    result = await ws.execute(f"stat {issue_path}/issue.json")
+    print(await result.stdout_str())
+
+    print("=== jq .title issue.json ===")
+    result = await ws.execute(f'jq ".title" {issue_path}/issue.json')
+    print(await result.stdout_str())
+
+    print("=== jq .state_name issue.json ===")
+    result = await ws.execute(f'jq ".state_name" {issue_path}/issue.json')
+    print(await result.stdout_str())
+
+    print("=== tree -L 1 /linear/ ===")
+    result = await ws.execute("tree -L 1 /linear/")
+    print(await result.stdout_str())
+
+    print(f"=== tree -L 1 teams/{first_team} ===")
+    result = await ws.execute(f"tree -L 1 /linear/teams/{first_team}/")
+    print(await result.stdout_str())
+
+    print("=== find issues -name '*.json' ===")
+    result = await ws.execute(
+        f'find /linear/teams/{first_team}/issues/ -name "*.json"'
+        " | head -n 5")
+    print(await result.stdout_str())
+
+    print("=== find teams -type d (directory filter) ===")
+    result = await ws.execute(f"find /linear/teams/{first_team}/ -type d"
+                              " | head -n 5")
+    print(await result.stdout_str())
+
+    # -path matches the display path; -size counts dirs and sizeless
+    # rendered files as 0 (so +0c drops them, -1k keeps them).
+    print("=== find team -path '*issues*' ===")
+    result = await ws.execute(f'find /linear/teams/{first_team}/'
+                              f' -path "*issues*" | head -n 5')
+    print(await result.stdout_str())
+
+    print("=== find team -maxdepth 1 -size +0c (dirs drop out) ===")
+    result = await ws.execute(
+        f"find /linear/teams/{first_team}/ -maxdepth 1 -size +0c")
+    print(f"  exit={result.exit_code}")
+    print(await result.stdout_str())
+
+    print(f"=== du -s teams/{first_team} (walk fallback) ===")
+    result = await ws.execute(f"du -s /linear/teams/{first_team}/")
+    print(await result.stdout_str())
+
+    print("=== grep Mirage issue.json ===")
+    result = await ws.execute(f'grep Mirage {issue_path}/issue.json')
+    print(await result.stdout_str())
+
+    print("=== rg Backlog team.json ===")
+    result = await ws.execute(
+        f"rg Backlog /linear/teams/{first_team}/team.json")
+    print(await result.stdout_str())
+
+    print("=== basename ===")
+    result = await ws.execute(f"basename {issue_path}/issue.json")
+    print(await result.stdout_str())
+
+    print("=== dirname ===")
+    result = await ws.execute(f"dirname {issue_path}/issue.json")
+    print(await result.stdout_str())
+
+    # ── glob expansion (exercises resolve_glob → readdir) ──
+    issues_dir = f"/linear/teams/{first_team}/issues"
+    print(f"=== echo {issues_dir}/* (glob) ===")
+    r = await ws.execute(f"echo {issues_dir}/*")
+    out = (await r.stdout_str()).strip()
+    print(f"  {out[:200]}")
+
+    print(f"\n=== for f in {issues_dir}/* (glob loop) ===")
+    r = await ws.execute(f"for f in {issues_dir}/*; do echo found:$f; done"
+                         " | head -n 3")
+    out = (await r.stdout_str()).strip()
+    for line in out.splitlines():
+        print(f"  {line[:120]}")
+
+    # ── mid-path glob: the team segment is the pattern, the literal
+    # tail keeps walking (lists teams once, then filters).
+    print("\n=== echo /linear/teams/*/issues (mid-path glob) ===")
+    r = await ws.execute("echo /linear/teams/*/issues")
+    out = (await r.stdout_str()).strip()
+    print(f"  {out[:200]}")
+    assert out.endswith("/issues"), "mid-path glob did not expand"
+
+    # A glob that matches nothing stays the literal word, so the
+    # command reports it like GNU coreutils.
+    print("\n=== cat /linear/teams/zz-none-*/team.json (no match) ===")
+    r = await ws.execute("cat /linear/teams/zz-none-*/team.json")
+    err = (await r.stderr_str()).strip()
+    print(f"  exit={r.exit_code}  {err[:120]}")
+    assert r.exit_code == 1 and "zz-none-*" in err
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/linear/linear_fuse.py

@@ -0,0 +1,76 @@
+# ========= 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
+import subprocess
+
+from dotenv import load_dotenv
+
+from mirage import Mount, MountMode, Workspace
+from mirage.resource.linear import LinearConfig, LinearResource
+
+load_dotenv(".env.development")
+
+config = LinearConfig(api_key=os.environ["LINEAR_API_KEY"])
+resource = LinearResource(config=config)
+
+with Workspace({"/linear/": Mount(resource, mode=MountMode.READ,
+                                  fuse=True)}) as ws:
+    mp = ws.fuse_mountpoint
+
+    print(f"=== FUSE MODE: mounted at {mp} ===\n")
+
+    print("--- os.listdir() teams ---")
+    teams = os.listdir(f"{mp}/teams")
+    for t in teams[:5]:
+        print(f"  {t}")
+
+    if teams:
+        team = teams[0]
+        team_path = f"{mp}/teams/{team}"
+
+        print(f"\n--- os.listdir() {team} ---")
+        contents = os.listdir(team_path)
+        for c in contents:
+            print(f"  {c}")
+
+        # Linear cannot report a file size before fetching, so an unopened
+        # team.json stats as 0 bytes; any open (cat/wc/cp) hydrates it, and
+        # stat then reports the real size (see docs/python/setup/fuse.mdx).
+        team_json = f"{team_path}/team.json"
+        print("\n--- size-unknown semantics on team.json ---")
+        print(f"  stat before open: {os.stat(team_json).st_size} bytes")
+        wc = subprocess.run(["wc", "-c", team_json],
+                            capture_output=True,
+                            text=True)
+        print(f"  wc -c           : {wc.stdout.split()[0]} bytes")
+        print(f"  stat after read : {os.stat(team_json).st_size} bytes")
+
+        print("\n--- open() team.json ---")
+        with open(f"{team_path}/team.json") as f:
+            data = json.loads(f.read())
+            name = data.get("team_name", "?")
+            key = data.get("team_key", "?")
+            print(f"  {key}: {name}")
+
+    print(f"\n>>> FUSE mounted at: {mp}")
+    print(">>> Open another terminal and run:")
+    print(f">>>   ls {mp}/teams/")
+    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/linear/linear_vfs.py

@@ -0,0 +1,82 @@
+# ========= 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.linear import LinearConfig, LinearResource
+
+load_dotenv(".env.development")
+
+config = LinearConfig(api_key=os.environ["LINEAR_API_KEY"])
+resource = LinearResource(config=config)
+
+
+async def main():
+    with Workspace({"/linear/": resource}, mode=MountMode.READ) as ws:
+        vos = sys.modules["os"]
+        print("=== VFS MODE ===\n")
+
+        print("--- os.listdir() root ---")
+        entries = vos.listdir("/linear")
+        for e in entries:
+            print(f"  {e}")
+
+        print("\n--- os.listdir() teams ---")
+        teams = vos.listdir("/linear/teams")
+        for t in teams[:5]:
+            print(f"  {t}")
+
+        if teams:
+            team = teams[0]
+            team_path = f"/linear/teams/{team}"
+
+            print(f"\n--- os.listdir() {team} ---")
+            contents = vos.listdir(team_path)
+            for c in contents:
+                print(f"  {c}")
+
+            print("\n--- open() team.json ---")
+            with open(f"{team_path}/team.json") as f:
+                data = json.loads(f.read())
+                print(f"  name: {data.get('team_name')}")
+                print(f"  key: {data.get('team_key')}")
+
+            issues_path = f"{team_path}/issues"
+            if vos.path.isdir(issues_path):
+                issues = vos.listdir(issues_path)
+                print(f"\n--- os.listdir() issues ({len(issues)}) ---")
+                for i in issues[:5]:
+                    print(f"  {i}")
+
+                if issues:
+                    issue_dir = f"{issues_path}/{issues[0]}"
+                    print("\n--- open() issue.json ---")
+                    with open(f"{issue_dir}/issue.json") as f:
+                        data = json.loads(f.read())
+                        print(f"  key: {data.get('issue_key')}")
+                        print(f"  title: {data.get('title')}")
+                        print(f"  state: {data.get('state_name')}")
+
+        records = ws.ops.records
+        total = sum(r.bytes for r in records)
+        print(f"\nStats: {len(records)} ops, {total} bytes")
+
+
+asyncio.run(main())