fix: 產出格式修正

README.md

@@ -82,9 +82,23 @@ pnpm --filter html-transform exec playwright-cli --version
 若環境還沒有 Chromium：
 
 ```bash
+HOME=/tmp \
+XDG_CACHE_HOME=/tmp \
+PLAYWRIGHT_DAEMON_SESSION_DIR=/tmp/ms-playwright/daemon \
 pnpm --filter html-transform exec playwright-cli install-browser chromium
 ```
 
+若是在受限制環境中執行（例如 home directory 唯讀、sandbox 不允許寫入 `~/.cache`），建議同時指定：
+
+```bash
+HOME=/tmp
+XDG_CACHE_HOME=/tmp
+PLAYWRIGHT_DAEMON_SESSION_DIR=/tmp/ms-playwright/daemon
+PLAYWRIGHT_BROWSERS_PATH=/tmp/ms-playwright
+```
+
+這樣 Playwright 的 browser、cache 與 daemon session 都會寫到可寫目錄。
+
 ## 設定檔
 
 設定檔不是工具執行的絕對必要條件；沒有設定檔時，工具會使用內建預設並讀取：
@@ -138,6 +152,99 @@ export default {
 
 `frontend`、`backend`、`output`、`plan` 等欄位不會被 `doctor` 或 `scan` 使用，不需要為本 MVP 加入設定檔。
 
+## 本 repo 實際執行
+
+這個 monorepo 目前要能穩定跑 `scan`，至少需要處理三件事：
+
+1. 根目錄 `ht.config.mjs` 將 prototype 指到 `./prototype`
+2. Playwright Chromium 已安裝
+3. 若根目錄 `.playwright/cli.config.json` 有指定 `channel`，需避免 `scan` 誤走系統 Chrome
+
+目前本 repo 的最小設定是：
+
+```js
+export default {
+  prototype: "./prototype",
+};
+```
+
+若根目錄 `.playwright/cli.config.json` 類似：
+
+```json
+{
+  "browser": {
+    "browserName": "chromium",
+    "launchOptions": {
+      "channel": "chromium"
+    }
+  }
+}
+```
+
+`scan` 可能會失敗，並出現類似：
+
+```text
+Chromium distribution 'chrome' is not found at /opt/google/chrome/chrome
+```
+
+原因是 `html-transform` 會在 `.ht/cache/playwright-cli` 底下呼叫 `playwright-cli`。在這種情況下，可在該工作目錄放一份最小覆寫設定：
+
+```text
+.ht/cache/playwright-cli/.playwright/cli.config.json
+```
+
+內容：
+
+```json
+{
+  "browser": {
+    "browserName": "chromium"
+  }
+}
+```
+
+在這個 repo 內，實際可重現的流程如下。
+
+1. 確認設定與 CLI：
+
+```bash
+pnpm --filter html-transform exec playwright-cli --version
+HOME=/tmp \
+XDG_CACHE_HOME=/tmp \
+PLAYWRIGHT_DAEMON_SESSION_DIR=/tmp/ms-playwright/daemon \
+PLAYWRIGHT_BROWSERS_PATH=/tmp/ms-playwright \
+node packages/html-transform/src/cli.js doctor
+```
+
+2. 安裝 Chromium：
+
+```bash
+HOME=/tmp \
+XDG_CACHE_HOME=/tmp \
+PLAYWRIGHT_DAEMON_SESSION_DIR=/tmp/ms-playwright/daemon \
+PLAYWRIGHT_BROWSERS_PATH=/tmp/ms-playwright \
+pnpm --filter html-transform exec playwright-cli install-browser chromium
+```
+
+3. 準備 Playwright CLI 的本地覆寫設定（只有在根目錄 `.playwright/cli.config.json` 含 `channel` 時需要）：
+
+```bash
+mkdir -p .ht/cache/playwright-cli/.playwright
+printf '%s\n' '{' '  "browser": {' '    "browserName": "chromium"' '  }' '}' > .ht/cache/playwright-cli/.playwright/cli.config.json
+```
+
+4. 執行 scan：
+
+```bash
+HOME=/tmp \
+XDG_CACHE_HOME=/tmp \
+PLAYWRIGHT_DAEMON_SESSION_DIR=/tmp/ms-playwright/daemon \
+PLAYWRIGHT_BROWSERS_PATH=/tmp/ms-playwright \
+node packages/html-transform/src/cli.js scan
+```
+
+在受限制 sandbox 中，`scan` 可能因為 Vite 無法綁定本機 port、或 Chromium 啟動時的系統呼叫受限而失敗。這種情況下，需要在不受 sandbox 限制的 shell 執行上面的 `scan` 指令。
+
 ## Doctor
 
 ```bash
@@ -157,6 +264,16 @@ node packages/html-transform/src/cli.js doctor
 node packages/html-transform/src/cli.js scan
 ```
 
+在本 repo 的受限制環境中，建議實際使用：
+
+```bash
+HOME=/tmp \
+XDG_CACHE_HOME=/tmp \
+PLAYWRIGHT_DAEMON_SESSION_DIR=/tmp/ms-playwright/daemon \
+PLAYWRIGHT_BROWSERS_PATH=/tmp/ms-playwright \
+node packages/html-transform/src/cli.js scan
+```
+
 `scan` 會自動：
 
 - 用 Vite static server 提供 prototype。
@@ -297,6 +414,6 @@ node packages/html-transform/src/cli.js scan
 ```bash
 pnpm --filter html-transform typecheck
 pnpm --filter html-transform test
-node packages/html-transform/src/cli.js doctor
-node packages/html-transform/src/cli.js scan
+HOME=/tmp XDG_CACHE_HOME=/tmp PLAYWRIGHT_DAEMON_SESSION_DIR=/tmp/ms-playwright/daemon PLAYWRIGHT_BROWSERS_PATH=/tmp/ms-playwright node packages/html-transform/src/cli.js doctor
+HOME=/tmp XDG_CACHE_HOME=/tmp PLAYWRIGHT_DAEMON_SESSION_DIR=/tmp/ms-playwright/daemon PLAYWRIGHT_BROWSERS_PATH=/tmp/ms-playwright node packages/html-transform/src/cli.js scan
 ```