feat: add VS Code tree explorer APIs and direct download endpoints

app.py

@@ -1,11 +1,18 @@
-"""OpenCode Full-Screen Gateway for Hugging Face Space.
+"""OpenCode Gateway & File Explorer for Hugging Face Space.
 
 Features:
-- Pure Full-Screen UI: Proxies directly to native OpenCode web UI with zero redundant sidebars.
-- Strict Security Gate: Unauthenticated requests see a locked authentication challenge.
-- Multi-factor support: Accepts valid dynamic 8-digit PIN and/or Master Authorization Token.
-- Internal loopback Basic Auth automated injection: Eliminates 401 Basic Realm prompt.
-- Frame Embedding: Strips X-Frame-Options and restrictive CSP so authorized parent apps embed cleanly.
+- Pure Full-Screen UI: Proxies directly to native OpenCode web UI.
+- VS Code Style File Explorer API:
+  * GET /__api/tree: Lists folders & files recursively with metadata.
+  * GET /__api/file: Previews text/code content.
+- Direct Download Endpoints:
+  * GET /dl/zip: One-tap ZIP archive download of the entire workspace.
+  * GET /dl/{path}: Direct file download with Content-Disposition attachment.
+- Strict Security Gatekeeper:
+  * Unauthenticated requests see a locked authentication challenge.
+  * Accepts valid dynamic 8-digit PIN and/or Master Authorization Token.
+  * Internal loopback Basic Auth automated injection (eliminates 401 Basic Realm prompt).
+  * Frame Embedding: Strips X-Frame-Options & restrictive CSP.
 - Full WebSocket & Streaming Support.
 - Bucket persistence to kacapower/ghar-storage.
 """
@@ -26,7 +33,7 @@ from typing import Optional
 import httpx
 from fastapi import FastAPI, HTTPException, Header, Query, Request, Response, WebSocket, WebSocketDisconnect
 from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import HTMLResponse, JSONResponse, StreamingResponse
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, StreamingResponse
 from starlette.background import BackgroundTask
 
 try:
@@ -55,6 +62,9 @@ ACCESS_PIN = os.getenv("ACCESS_PIN", "").strip()
 HF_READ_TOKEN = os.getenv("HF_READ_TOKEN", "").strip() or os.getenv("HF_TOKEN", "").strip()
 DIRECT_SESSION_TIMEOUT = int(os.getenv("DIRECT_SESSION_TIMEOUT", "600"))
 
+TEXT_LIMIT = 512 * 1024
+ZIP_LIMIT = 500 * 1024 * 1024
+
 state = {
     "last_direct_session": 0.0,
     "direct_mode_pause_external": os.getenv("DIRECT_MODE_PAUSE", "1") in {"1", "true", "True"},
@@ -171,6 +181,46 @@ button:hover {{ background:#2ea043; }}
 </html>"""
 
 
+# ---------------- PATH HELPERS ----------------
+
+def _root(root: str = "workspace") -> Path:
+    if root not in ROOTS:
+        raise HTTPException(status_code=404, detail=f"unknown root {root!r}")
+    return ROOTS[root].resolve()
+
+
+def _resolve(root: str, rel: str) -> Path:
+    base = _root(root)
+    rel = rel.lstrip("/")
+    target = (base / rel).resolve() if rel else base
+    if target != base and base not in target.parents:
+        raise HTTPException(status_code=403, detail="path escapes root")
+    return target
+
+
+def _rel(base: Path, target: Path) -> str:
+    try:
+        rel = target.relative_to(base).as_posix()
+    except ValueError:
+        return ""
+    return "" if rel == "." else rel
+
+
+def _entry(base: Path, p: Path) -> dict:
+    try:
+        st = p.stat()
+    except OSError:
+        st = None
+    is_dir = p.is_dir()
+    return {
+        "name": p.name,
+        "path": _rel(base, p),
+        "type": "dir" if is_dir else "file",
+        "size": 0 if is_dir or st is None else st.st_size,
+        "mtime": 0 if st is None else int(st.st_mtime),
+    }
+
+
 # ---------------- HEALTH ENDPOINT ----------------
 
 @app.get("/__health")
@@ -190,11 +240,103 @@ async def health(request: Request):
     }
 
 
+# ---------------- VS CODE FILE EXPLORER APIS ----------------
+
+@app.get("/__api/tree")
+async def api_tree(request: Request, path: str = ""):
+    if not is_auth_valid(request):
+        raise HTTPException(status_code=401, detail="Unauthorized")
+
+    base = _root("workspace")
+    target = _resolve("workspace", path)
+    if not target.exists():
+        raise HTTPException(status_code=404, detail="not found")
+
+    entries = []
+    try:
+        children = list(target.iterdir())
+    except OSError as exc:
+        raise HTTPException(status_code=403, detail=str(exc))
+
+    for child in children:
+        # Hide internal git and cache folders from VS Code explorer view
+        if child.name in {".git", "__pycache__", "node_modules"}:
+            continue
+        if not child.is_symlink() or child.exists():
+            entries.append(_entry(base, child))
+
+    entries.sort(key=lambda e: (e["type"] != "dir", e["name"].lower()))
+    return {"path": _rel(base, target), "entries": entries}
+
+
+@app.get("/__api/file")
+async def api_file(request: Request, path: str = ""):
+    if not is_auth_valid(request):
+        raise HTTPException(status_code=401, detail="Unauthorized")
+
+    target = _resolve("workspace", path)
+    if not target.is_file():
+        raise HTTPException(status_code=404, detail="not a file")
+
+    size = target.stat().st_size
+    with target.open("rb") as fh:
+        head = fh.read(4096)
+    binary = b"\x00" in head
+
+    payload = {
+        "name": target.name,
+        "path": _rel(_root("workspace"), target),
+        "size": size,
+        "binary": binary,
+        "content": None,
+    }
+    if not binary:
+        with target.open("rb") as fh:
+            raw = fh.read(TEXT_LIMIT + 1)
+        payload["content"] = raw[:TEXT_LIMIT].decode("utf-8", errors="replace")
+    return payload
+
+
+# ---------------- DIRECT DOWNLOAD ROUTES ----------------
+
+@app.get("/dl/zip")
+async def download_workspace_zip(request: Request):
+    if not is_auth_valid(request):
+        raise HTTPException(status_code=401, detail="Unauthorized")
+
+    base = _root("workspace")
+    buf = BytesIO()
+    total = 0
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+        for child in sorted(base.rglob("*")):
+            if child.is_file() and not any(part in {".git", "__pycache__", "node_modules"} for part in child.parts):
+                total += child.stat().st_size
+                if total > ZIP_LIMIT:
+                    raise HTTPException(status_code=413, detail="Workspace archive exceeds size limit")
+                zf.write(child, child.relative_to(base).as_posix())
+
+    buf.seek(0)
+    filename = f"workspace_{datetime.now().strftime('%Y%m%d_%H%M%S')}.zip"
+    headers = {"Content-Disposition": f'attachment; filename="{filename}"'}
+    return StreamingResponse(buf, media_type="application/zip", headers=headers)
+
+
+@app.get("/dl/{path:path}")
+async def direct_file_download(path: str, request: Request):
+    if not is_auth_valid(request):
+        raise HTTPException(status_code=401, detail="Unauthorized")
+
+    target = _resolve("workspace", path)
+    if not target.is_file():
+        raise HTTPException(status_code=404, detail="File not found")
+
+    return FileResponse(target, filename=target.name, media_type="application/octet-stream")
+
+
 # ---------------- PROXY TO OPENCODE ----------------
 
 def _proxy_headers(request: Request) -> dict:
     headers = {k: v for k, v in request.headers.items() if k.lower() not in HOP_HEADERS}
-    # Inject internal Basic Auth so OpenCode server on 127.0.0.1 never rejects with 401
     headers["authorization"] = INTERNAL_BASIC_AUTH
     return headers
 
@@ -212,14 +354,12 @@ def _response_headers(upstream: httpx.Response) -> dict:
     methods=["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"],
 )
 async def proxy(path: str, request: Request):
-    # Verify authentication
     if not is_auth_valid(request):
         if request.method == "GET" and "text/html" in request.headers.get("accept", ""):
             err = "Invalid PIN" if request.query_params.get("pin") else ""
             return HTMLResponse(get_lock_html(err), status_code=401 if err else 200)
         return JSONResponse({"error": "Unauthorized: 8-digit PIN or valid authorization required"}, status_code=401)
 
-    # Clean query parameters for upstream OpenCode
     params = [(k, v) for k, v in request.query_params.multi_items() if k not in {"pin", "token", "iframe"}]
     url = httpx.URL(f"{UPSTREAM}/{path}", params=params) if params else f"{UPSTREAM}/{path}"
 
@@ -244,7 +384,6 @@ async def proxy(path: str, request: Request):
         background=BackgroundTask(upstream.aclose),
     )
 
-    # Persist auth cookie for iframe and sub-requests
     pin_val = request.query_params.get("pin") or request.cookies.get("opencode_auth")
     if pin_val and is_pin_valid(pin_val):
         resp.set_cookie("opencode_auth", pin_val, max_age=86400, httponly=True, samesite="none", secure=True)
@@ -258,7 +397,6 @@ async def ws_proxy(websocket: WebSocket, path: str):
         await websocket.close(code=1011)
         return
 
-    # Check WebSocket authorization
     pin_val = websocket.query_params.get("pin") or websocket.cookies.get("opencode_auth")
     token_val = websocket.query_params.get("token")
     auth_ok = is_pin_valid(pin_val) or (HF_READ_TOKEN and token_val == HF_READ_TOKEN)
@@ -273,8 +411,6 @@ async def ws_proxy(websocket: WebSocket, path: str):
     query = "&".join(f"{k}={v}" for k, v in websocket.query_params.items() if k not in {"pin", "token"})
     target = f"{UPSTREAM_WS}/{path}" + (f"?{query}" if query else "")
     subprotocols = [p.strip() for p in protocol.split(",")] if protocol else None
-
-    # Forward with Basic Auth headers
     extra_headers = {"Authorization": INTERNAL_BASIC_AUTH}
 
     try: