folderui 0.1.0__py3-none-any.whl

folderui/__init__.py

@@ -0,0 +1,6 @@
+"""folderui：把資料夾變成給人類與 AI agent 用的立即式 GUI。"""
+from .server import Server
+from .session import Session
+from .ui import FolderUI
+
+__all__ = ["FolderUI", "Server", "Session"]

folderui/fsutil.py

@@ -0,0 +1,28 @@
+"""檔案工具：所有寫入都是原子的（先寫暫存檔再 rename），避免讀到半個檔案。"""
+import json
+import os
+from pathlib import Path
+
+
+def write_text(path: Path, text: str, mode: int | None = None) -> None:
+    tmp = path.with_name(f".{path.name}.tmp")
+    tmp.write_text(text, encoding="utf-8")
+    if mode is not None:
+        os.chmod(tmp, mode)
+    os.replace(tmp, path)
+
+
+def write_json(path: Path, data) -> None:
+    write_text(path, json.dumps(data, ensure_ascii=False, indent=2) + "\n")
+
+
+def read_text(path: Path, default=None):
+    try:
+        return path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return default
+
+
+def read_json(path: Path, default=None):
+    text = read_text(path)
+    return default if text is None else json.loads(text)

folderui/server.py

@@ -0,0 +1,68 @@
+"""多人用的伺服器：一個執行緒依序處理所有客戶端的請求，並推播給客戶端。
+
+    客戶端 ──call(who, cmd)──▶ Server.handle()     請求／回應（同步）
+    客戶端 ◀──push(who, msg)── Server              推播（非同步）
+
+handle() raise 的例外會傳回呼叫端（ValueError 代表規則不允許）。
+推播走客戶端的無上限佇列，伺服器永遠不會等待客戶端，所以不會死鎖。
+"""
+import queue
+import threading
+import traceback
+
+
+class Server:
+    def __init__(self):
+        self.clients: dict = {}
+        self._requests: queue.Queue = queue.Queue()
+        self._stopped = False
+
+    # ---- 子類別實作 ----
+
+    def handle(self, who, cmd):
+        raise NotImplementedError
+
+    def on_start(self) -> None:
+        pass
+
+    # ---- API ----
+
+    def connect(self, who, client) -> None:
+        """註冊一個可以接收推播的客戶端（任何有 push(msg) 的物件）。"""
+        self.clients[who] = client
+
+    def call(self, who, cmd, timeout: float = 30):
+        box: queue.Queue = queue.Queue(maxsize=1)
+        self._requests.put((who, cmd, box))
+        try:
+            ok, value = box.get(timeout=timeout)
+        except queue.Empty:
+            raise TimeoutError("伺服器沒有回應") from None
+        if ok:
+            return value
+        raise value
+
+    def push(self, who, msg) -> None:
+        self.clients[who].push(msg)
+
+    def start(self) -> threading.Thread:
+        t = threading.Thread(target=self.run, name="folderui:server", daemon=True)
+        t.start()
+        return t
+
+    def stop(self) -> None:
+        self._stopped = True
+
+    def run(self) -> None:
+        self.on_start()
+        while not self._stopped:
+            try:
+                who, cmd, box = self._requests.get(timeout=0.2)
+            except queue.Empty:
+                continue
+            try:
+                box.put((True, self.handle(who, cmd)))
+            except Exception as e:
+                if not isinstance(e, ValueError):
+                    traceback.print_exc()
+                box.put((False, e))

folderui/session.py

@@ -0,0 +1,44 @@
+"""程式型 agent 用的客戶端：和按鈕腳本走同一個檔案協定。"""
+import json
+import time
+from pathlib import Path
+
+from .fsutil import read_text, write_text
+
+
+class Session:
+    def __init__(self, path: str | Path, poll: float = 0.1):
+        self.root = Path(path)
+        self.poll = poll
+
+    def ready(self, timeout: float | None = None) -> bool:
+        """等到資料夾畫好（第一次可以讀到按鈕列表）。"""
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while not (self.root / ".buttons.json").exists():
+            if deadline is not None and time.monotonic() > deadline:
+                return False
+            time.sleep(self.poll)
+        return True
+
+    def buttons(self) -> dict[str, dict]:
+        """目前可按的按鈕 {路徑: {hint, options}}；空的代表已結束（或還輪不到你）。"""
+        return json.loads(read_text(self.root / ".buttons.json", "{}"))
+
+    def read(self, path: str) -> str:
+        return read_text(self.root / path, "")
+
+    def press(self, path: str, *args: str, timeout: float | None = None) -> tuple[bool, str]:
+        """按下按鈕並等待回應，回傳 (是否成功, 回應內容)。"""
+        request = self.root / ".request"
+        if request.exists():
+            raise RuntimeError("上一個操作還在等待回應")
+        (self.root / ".done").unlink(missing_ok=True)
+        write_text(request, "".join(f"{x}\0" for x in (path, *args)))
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while request.exists():
+            if deadline is not None and time.monotonic() > deadline:
+                raise TimeoutError("等待回應逾時")
+            time.sleep(self.poll)
+        code, _, text = read_text(self.root / ".response", "1\n").partition("\n")
+        (self.root / ".done").unlink(missing_ok=True)
+        return code.strip() == "0", text.rstrip("\n")

folderui/ui.py

@@ -0,0 +1,261 @@
+"""FolderUI：把一個資料夾變成給人類或 AI agent 用的立即式 GUI。
+
+子類別實作三個方法：
+    draw()                 每一幀重新宣告畫面：file()、button()、reply()。不可修改狀態。
+    action(name, args)     按鈕被按下時呼叫：回傳文字，或 raise 代表失敗。只有這裡修改狀態。
+    receive(msg)           收到 push() 的訊息（例如伺服器推播）。
+
+資料夾裡只有 draw() 宣告的檔案和按鈕腳本（<path>.sh）。執行按鈕腳本後，腳本會一直等待，
+直到「操作處理完之後，第一個有按鈕可按的畫面」出現（或 close()）才回應：
+    action 的回傳值 + 這段期間的 notify() + reply() + 目前可按的按鈕
+
+腳本與主機之間的協定（隱藏檔）：
+    .request    腳本寫入：按鈕路徑與參數，以 NUL 分隔
+    .response   主機寫入：第一行為 exit code，之後為回應內容
+    .done       主機回應後把 .request 改名為 .done；腳本讀完回應後刪除它
+    .buttons.json  目前的按鈕列表（給程式型 agent 用）
+"""
+import json
+import os
+import queue
+import shlex
+import sys
+import threading
+import time
+import traceback
+from pathlib import Path
+
+from .fsutil import write_text
+
+PROTOCOL_FILES = (".request", ".request.new", ".response", ".done")
+
+SCRIPT = """\
+#!/bin/sh
+# folderui 按鈕：{name}{hint}
+cd {root} || exit 1
+printf '%s\\0' {qname} "$@" > .request.new
+if [ -e .request ]; then
+  if cmp -s .request .request.new; then
+    rm -f .request.new
+    echo "⏳ 繼續等待…" >&2
+  else
+    rm -f .request.new
+    echo "❌ 上一個操作還在等待回應；再執行一次同樣的指令可以繼續等待"
+    exit 1
+  fi
+elif [ -e .done ] && cmp -s .done .request.new; then
+  rm -f .request.new
+else
+  rm -f .done .response
+  mv .request.new .request
+  echo "⏳ 已送出，等待中…" >&2
+fi
+limit=$(( ${{FOLDERUI_TIMEOUT:-0}} * 5 )); i=0
+while [ -e .request ]; do
+  sleep 0.2; i=$((i+1))
+  if [ "$limit" -gt 0 ] && [ "$i" -ge "$limit" ]; then
+    echo "⏳ 還在等待中，再執行一次同樣的指令即可繼續等待"
+    exit 2
+  fi
+done
+code=$(head -n 1 .response)
+tail -n +2 .response
+rm -f .done
+exit "$code"
+"""
+
+
+def _check_path(path: str) -> str:
+    parts = path.split("/")
+    if path.startswith("/") or any(not p or p.startswith(".") for p in parts):
+        raise ValueError(f"路徑不能是絕對路徑、空段落或隱藏檔：{path!r}")
+    return path
+
+
+class FolderUI:
+    poll = 0.1
+    close_grace = 5.0
+
+    def __init__(self, path: str | Path):
+        self.root = Path(path).resolve()
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.closed = False
+        self._inbox: queue.Queue = queue.Queue()
+        self._files: dict[str, str] = {}
+        self._buttons: dict[str, tuple[str, list[str] | None]] = {}
+        self._reply = ""
+        self._disk_files: dict[str, str] = {}      # 磁碟上由本框架管理的檔案
+        self._disk_scripts: dict[str, str] = {}
+        self._notes: list[str] = []
+        self._pending: tuple[int, str] | None = None
+        self._pending_button: tuple[str, str] | None = None  # (路徑, hint)：回應被讀走前保留它的腳本
+
+    # ---- 子類別實作 ----
+
+    def draw(self) -> None:
+        pass
+
+    def action(self, name: str, args: list[str]) -> str | None:
+        raise ValueError(f"沒有處理按鈕 {name}")
+
+    def receive(self, msg) -> None:
+        pass
+
+    # ---- 在 draw() 中呼叫 ----
+
+    def file(self, path: str, content: str) -> None:
+        self._files[_check_path(path)] = content
+
+    def button(self, path: str, hint: str = "", options: list[str] | None = None) -> None:
+        self._buttons[_check_path(path)] = (hint, options)
+
+    def reply(self, text: str) -> None:
+        self._reply = text
+
+    # ---- 在 action() / receive() 中呼叫 ----
+
+    def notify(self, text: str) -> None:
+        """累積一則消息，在下一次回應時一起送出。"""
+        self._notes.append(text)
+
+    def close(self) -> None:
+        """結束：移除所有按鈕，回應正在等待的腳本，然後停止。"""
+        self.closed = True
+
+    # ---- 給其他執行緒 ----
+
+    def push(self, msg) -> None:
+        self._inbox.put(msg)
+
+    def start(self) -> threading.Thread:
+        t = threading.Thread(target=self.run, name=f"folderui:{self.root.name}", daemon=True)
+        t.start()
+        return t
+
+    # ---- 主迴圈 ----
+
+    def run(self) -> None:
+        for name in PROTOCOL_FILES:
+            (self.root / name).unlink(missing_ok=True)
+        self._redraw()
+        deadline = None
+        while not (self.closed and self._pending is None and self._pending_button is None):
+            if self.closed and self._pending is None:  # 已結束：最後的回應最多等 close_grace 秒被讀走
+                deadline = deadline or time.monotonic() + self.close_grace
+                if time.monotonic() > deadline:
+                    break
+            changed = False
+            try:
+                msg = self._inbox.get(timeout=self.poll)
+                self._call(self.receive, msg)
+                changed = True
+            except queue.Empty:
+                pass
+            changed |= self._take_request()
+            changed |= self._drain()
+            if self._pending is None and self._pending_button and not (self.root / ".done").exists():
+                self._pending_button = None  # 回應已被讀走
+                changed = True
+            if changed:
+                self._redraw()
+            if self._pending is not None and (self._buttons or self.closed):
+                self._respond()
+
+    def _drain(self) -> bool:
+        changed = False
+        while True:
+            try:
+                msg = self._inbox.get_nowait()
+            except queue.Empty:
+                return changed
+            self._call(self.receive, msg)
+            changed = True
+
+    def _take_request(self) -> bool:
+        if self._pending is not None:
+            return False
+        try:
+            raw = (self.root / ".request").read_bytes()
+        except FileNotFoundError:
+            return False
+        name, *args = [x.decode("utf-8", "replace") for x in raw.split(b"\0")[:-1]] or [""]
+        if name not in self._buttons:
+            self._pending = (1, f"❌ 按鈕 {name} 已經不存在")
+            return True
+        self._pending_button = (name, self._buttons[name][0])
+        try:
+            result = self.action(name, args)
+            self._pending = (0, result or "")
+        except Exception as e:
+            if not isinstance(e, ValueError):  # ValueError 視為使用者錯誤，其餘是程式 bug
+                traceback.print_exc()
+            self._pending = (1, f"❌ {e}")
+        return True
+
+    def _respond(self) -> None:
+        code, text = self._pending
+        parts = [text] if text else []
+        parts += self._notes
+        if self._reply:
+            parts.append(self._reply)
+        if self.closed:
+            parts.append("── 已結束 ──")
+        else:
+            lines = ["── 可以做的事 ──"]
+            for path, (hint, options) in self._buttons.items():
+                lines.append(f"./{path}.sh" + (f"  {hint}" if hint else ""))
+                if options:
+                    lines.append("    選項：" + " / ".join(options))
+            parts.append("\n".join(lines))
+        write_text(self.root / ".response", f"{code}\n" + "\n\n".join(parts) + "\n")
+        os.replace(self.root / ".request", self.root / ".done")
+        self._notes = []
+        self._pending = None
+
+    def _redraw(self) -> None:
+        self._files, self._buttons, self._reply = {}, {}, ""
+        self._call(self.draw)
+        if self.closed:
+            self._buttons = {}
+        scripts = {f"{p}.sh": self._script(p, hint) for p, (hint, _) in self._buttons.items()}
+        if self._pending_button:  # 逾時後重新執行同一個指令＝繼續等待或拿回應，所以腳本要留到回應被讀走
+            name, hint = self._pending_button
+            scripts.setdefault(f"{name}.sh", self._script(name, hint))
+        self._sync(self._disk_files, self._files, None)
+        self._sync(self._disk_scripts, scripts, 0o755)
+        write_text(self.root / ".buttons.json", json.dumps(
+            {p: {"hint": h, "options": o} for p, (h, o) in self._buttons.items()},
+            ensure_ascii=False, indent=2) + "\n")
+
+    def _sync(self, disk: dict[str, str], want: dict[str, str], mode: int | None) -> None:
+        for path in set(disk) - set(want):
+            (self.root / path).unlink(missing_ok=True)
+            self._prune(self.root / path)
+            del disk[path]
+        for path, content in want.items():
+            if disk.get(path) != content:
+                target = self.root / path
+                target.parent.mkdir(parents=True, exist_ok=True)
+                write_text(target, content, mode)
+                disk[path] = content
+
+    def _prune(self, path: Path) -> None:
+        for d in path.parents:
+            if d == self.root:
+                return
+            try:
+                d.rmdir()
+            except OSError:
+                return
+
+    def _script(self, name: str, hint: str) -> str:
+        hint = " ".join(hint.split())
+        return SCRIPT.format(name=name, hint=f" — {hint}" if hint else "",
+                             root=shlex.quote(str(self.root)), qname=shlex.quote(name))
+
+    def _call(self, fn, *args) -> None:
+        try:
+            fn(*args)
+        except Exception:
+            print(f"[folderui:{self.root.name}] {fn.__name__}() 發生錯誤：", file=sys.stderr)
+            traceback.print_exc()

folderui-0.1.0.dist-info/METADATA

@@ -0,0 +1,140 @@
+Metadata-Version: 2.5
+Name: folderui
+Version: 0.1.0
+Summary: Turn a folder into an immediate-mode GUI for humans and AI agents: *.md files are the view, *.sh files are buttons.
+Project-URL: Homepage, https://github.com/xiao-e-yun/folderui
+Project-URL: Repository, https://github.com/xiao-e-yun/folderui
+Author: xiao-e-yun
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,gui,immediate-mode,llm,multiplayer,turn-based
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# folderui
+
+把**資料夾變成立即式 GUI**，給人類和 AI agent 使用。資料夾裡只有兩種東西：
+
+- `*.md` 等檔案：畫面（隨時可以 `cat`）
+- `*.sh`：按鈕（只有現在能按的才會出現）
+
+執行按鈕後，腳本會**一直等到你需要做下一個決定**才回應，並印出：操作結果 + 這段期間發生的事 + 目前狀況 + 可以按的按鈕。
+所以 agent 的迴圈就是「執行按鈕 → 讀回應 → 執行下一個按鈕」，不需要另外等待或輪詢。
+
+```sh
+pip install folderui     # 或 uv add folderui；只用標準函式庫，需要 POSIX shell
+```
+
+```console
+$ ./bid.sh 40
+⏳ 已送出，等待中…              ← 其他人還在出價，腳本卡住
+✅ 已出價 40
+開標：bob 5、carol 15、你 40
+🔨 你以 40 得標 …
+🔔 bob 拍賣「月光琉璃盞」…
+
+── 可以做的事 ──
+./bid.sh  <金額 1-60>  密封出價
+./pass.sh  不出價
+```
+
+## 寫一個 UI
+
+```python
+from folderui import FolderUI
+
+class Guess(FolderUI):
+    def draw(self):                      # 每一幀重新宣告畫面，不可修改狀態
+        self.file("rules.md", "猜 1-100")
+        self.button("guess", "<數字>")
+        self.reply(f"已經猜了 {len(self.tries)} 次")
+
+    def action(self, name, args):        # 按鈕被按下：回傳文字，或 raise ValueError 代表失敗
+        n = int(args[0])
+        ...
+        return "太大"
+
+Guess("/tmp/my-ui").run()
+```
+
+| 方法 | 在哪裡呼叫 | 作用 |
+|---|---|---|
+| `file(path, content)` | `draw()` | 宣告一個檔案；沒宣告的會自動刪除 |
+| `button(path, hint, options=None)` | `draw()` | 宣告一個按鈕 → `<path>.sh`，路徑可以分層（`players/2/kick`） |
+| `reply(text)` | `draw()` | 腳本回應時印出的目前狀況 |
+| `notify(text)` | `action()` / `receive()` | 累積一則消息，下一次回應時送出 |
+| `close()` | `action()` / `receive()` | 結束：移除按鈕、回應等待中的腳本 |
+| `push(msg)` | 其他執行緒 | 送訊息給這個 UI，會呼叫 `receive(msg)` |
+
+**回應規則只有一條**：操作處理完之後，第一個「有按鈕可按」的畫面出現時（或 `close()`）才回應。
+
+- 輸入錯誤 → 狀態沒變、按鈕還在 → 立刻回應（`raise` 的訊息，exit code 1）
+- 查詢類操作 → 按鈕還在 → 立刻回應
+- 送出後要等別人 → 沒有按鈕 → 等到輪到你
+
+## 多人：1 個伺服器 + N 個客戶端
+
+```python
+class MyServer(Server):
+    def handle(self, who, cmd):          # 純邏輯；raise ValueError 代表規則不允許
+        ...
+        for p in self.clients:
+            self.push(p, Update(...))     # 推播給客戶端
+        return "✅ 已出價"
+
+class PlayerUI(FolderUI):
+    def action(self, name, args):
+        return self.server.call(self.me, ("bid", int(args[0])))   # 同步呼叫，例外會傳回來
+    def receive(self, update):
+        self.view = update.view          # 伺服器推播 → 框架自動重畫
+
+server = MyServer()
+for i in range(n):
+    server.connect(i, PlayerUI(f"{root}/player_{i}", server, i))
+server.start()
+for ui in server.clients.values():
+    ui.start()
+```
+
+框架不管多人同步：伺服器在一個執行緒依序處理請求，推播走無上限佇列（伺服器永遠不等客戶端）。
+
+## 程式型 agent
+
+```python
+from folderui import Session
+s = Session("/tmp/folderui-auction-xxxx/player_0")
+s.ready()
+while buttons := s.buttons():            # {路徑: {hint, options}}，空的代表結束
+    ok, text = s.press("bid", "40")
+```
+
+## 細節
+
+- 腳本預設無限等待。設定 `FOLDERUI_TIMEOUT=秒數` 會在逾時後以 exit code 2 結束；
+  **再執行一次同樣的指令即可繼續等待或拿到回應**（不會重複送出）。回應被讀走之前，該按鈕的腳本會保留。
+- 協定檔案都是隱藏檔：`.request`、`.response`、`.done`、`.buttons.json`。
+  不能執行腳本的 agent 也可以直接寫 `.request`（按鈕路徑與參數以 NUL 分隔）。
+
+## 範例
+
+```sh
+uv run python examples/guess.py                     # 單人：猜數字
+uv run python examples/auction.py --players 4 --rounds 3   # 多人：英式拍賣（玩家 + 觀眾）
+uv run python examples/auction_bot.py <資料夾> bot0   # 拍賣用的隨機 bot
+```
+
+## 開發
+
+```sh
+uv sync
+uv run pytest
+```
+
+發布：在 PyPI 設定 trusted publisher（repo `xiao-e-yun/folderui`、workflow `publish.yml`、environment `pypi`），
+之後改 `pyproject.toml` 的版本號並推送 `v*` tag 就會自動發布。

folderui-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+folderui/__init__.py,sha256=DgcWogffdAcswuQ4xnVbsra6JwV1PVDGyhHiTo6W9V4,206
+folderui/fsutil.py,sha256=ddo13cW3NdwZQSr9y2vppC1xVnPlB1QVgzrKplS6Nog,799
+folderui/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+folderui/server.py,sha256=_gEhObn4GtDpl5AJQHkbCEhm07MyAsW8HpZUNFoQNNk,2130
+folderui/session.py,sha256=U-c0Pi1YAh6_eSXONoUPNsaO4UIi0FxvT2ORzN6dgHA,1943
+folderui/ui.py,sha256=hGJ2BLCdTYqdd0bDFCL7L2J4AJnVBvTilpTR2T17uSU,9723
+folderui-0.1.0.dist-info/METADATA,sha256=lH5hDlDZU3QlQQD3fdWydJ9kwy5O-zCez1HuFR3aW1c,5361
+folderui-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+folderui-0.1.0.dist-info/licenses/LICENSE,sha256=tcJlcDzyGAbI59TkI8E2ePZroQpo4WJyXpSq_Bqa-PI,1067
+folderui-0.1.0.dist-info/RECORD,,

folderui-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

folderui-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xiao-e-yun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.