# AGENTS.md

## 專案概念

HTML Transform 是 prototype-driven orchestration framework。目標是把 HTML prototype 轉成可 review、可驗證、可追溯的 Vuetify frontend output。

這個 repo 目前是 MVP，不是完整產品。核心價值先放在 CLI pipeline 與 artifact-first workflow：

```text
scan -> plan -> run -> diff -> verify
```

所有中間產物都寫到 `.ht/`，生成結果寫到 `output` 設定指向的資料夾，預設是 `packages/result`。

## 目前 MVP 狀態

已完成：

- `ht` CLI 骨架：`scan`、`plan`、`run`、`diff`、`verify`、`go`、`status`、`doctor`
- `ht.config.js/json/ts` 設定載入
- deterministic HTML evidence extraction
- `.ht/cache/prototype`
- `.ht/spec/*.spec.json`
- `.ht/spec/*.validation.json`
- `.ht/spec/*.ui-contract.md`
- `.ht/plan/tasklist.json`
- `.ht/plan/project-conventions.md`
- `.ht/plan/api-contract.md`
- `.ht/plan/component-mapping.json`
- `.ht/runs/<runId>/`
- `.ht/diff/*.diff.html`
- `.ht/verify/verification-report.json`
- 基本 E2E 測試

尚未完成，不能假裝已完成：

- Playwright static server
- 真實 full-page screenshot
- 真實 DOM snapshot API
- 真實 accessibility tree API
- vision-based decomposition/extraction
- Zod schema validation
- 真實 coding agent invocation
- 真實 visual similarity scoring
- 完整 DOM-level 與 flow-level smoke tests

目前 screenshot 是 placeholder PNG，`diff` score 是 deterministic placeholder。

## 套件管理

使用 pnpm，不使用 npm 或 yarn。

```bash
pnpm install
pnpm test
pnpm typecheck
```

不要新增 `package-lock.json` 或 `yarn.lock`。lockfile 應該是 `pnpm-lock.yaml`。

## Playwright CLI 決策

這個專案使用 `@playwright/cli`，透過 shell command 操作 `playwright-cli`，不使用 MCP。

原因：

- PRD 的 pipeline 是 coding-agent orchestration，CLI 比 MCP 更適合放進可重跑 stage。
- CLI invocation 較容易寫入 `.ht/runs`、logs、metadata 與 verification report。
- 專案應避免依賴使用者全域環境。

解析順序在 `src/lib/playwright-cli.js`：

1. `node_modules/.bin/playwright-cli`
2. 全域 `playwright-cli`
3. `npx --no-install playwright-cli`

`doctor` 必須能顯示 `playwright-cli (local)`、`playwright-cli (global)` 或 missing。

專案級 Codex runtime skill 放在 `.codex/skills/playwright-cli`，本機全域也可能有一份在 `~/.codex/skills/playwright-cli`。處理 browser automation、snapshot、screenshot、trace、video、test generation 或 local web app testing 時，Codex 應優先使用專案級 skill；若沒有自動觸發，先讀取 `.codex/skills/playwright-cli/SKILL.md` 再操作。

安裝瀏覽器：

```bash
pnpm playwright-cli:install-browser
```

Linux CI 或乾淨容器若需要系統 dependency，先 dry-run：

```bash
npx --no-install playwright-cli install-browser --with-deps --dry-run
```

## 預設資料夾

預設 config：

```text
packages/prototype   # HTML prototype
packages/web         # 既有 Vuetify frontend
packages/api         # backend API/schema
packages/result      # output
.ht                  # tool artifacts
```

目前 repo 可能沒有預設輸入資料夾。這時 `doctor` 回報 missing 是正確行為，不是 bug。

## 開發原則

- 遵守 PRD 的 artifact-first 思路。
- 不要把 placeholder 包裝成完整實作。
- 每個 stage 的失敗、缺少環境、skipped 都要明確寫入 report 或 CLI output。
- 優先做可重跑、可檢查、可追溯的 deterministic behavior。
- 不要讓 agent 修改 `prototype/`、`frontend/`、`backend/` 原始輸入資料夾；生成與執行 artifact 應限制在 `output/` 與 `.ht/`。
- 保持 MVP 邊界，避免加泛用抽象或一開始支援所有 monorepo 形態。

## JSDoc 原則

- 依專案的 `jsdoc` skill 撰寫 JSDoc；這裡只補充 HTML Transform 專案特有規則。
- JavaScript 的 JSDoc 優先補在 exported API、stage 入口、跨模組 helper，或描述非顯而易見契約與限制的位置；不為測試檔或區域性小函式刻意補註解。
- JSDoc 使用繁體中文，並把說明重點放在 artifact、pipeline stage、MVP 限制、cache/placeholder 行為、輸入輸出契約等專案脈絡。
- 不新增 `jsdoc` 產生 HTML 文件的設定、script 或 build step，除非使用者明確要求。
- 補 JSDoc 不應順手 refactor、改行為、加抽象或擴大 scope。

## 驗證

完成任何改動後至少執行：

```bash
pnpm test
pnpm typecheck
```

若改到環境偵測、Playwright CLI、設定載入，也執行：

```bash
node src/cli.js doctor
```

若改到 stage pipeline，應確認 E2E 測試仍通過，或新增/更新 `test/cli-e2e.test.js`。

## 重要檔案

- `PRD.md`：產品需求來源。
- `README.md`：使用方式與 MVP 限制。
- `src/cli.js`：CLI command router。
- `src/lib/config.js`：config loading。
- `src/lib/html.js`：deterministic HTML evidence extraction。
- `src/lib/playwright-cli.js`：Playwright CLI resolution。
- `src/stages/*.js`：各 stage 實作。
- `test/cli-e2e.test.js`：完整 CLI pipeline 測試。

## 下一個最重要的方向

下一步最值得做的是把 Stage 1 做真：

- local static server
- `playwright-cli` 三 viewport screenshot
- network/resource failure metadata
- DOM snapshot artifact
- accessibility snapshot artifact
- cache hit 時跳過 screenshot

這完成後，工具才會真正開始觀察 browser-rendered prototype，而不是只解析 HTML source。