# AGENTS.md

## 專案概念

HTML Transform 是 prototype evidence 工具。目標是把 HTML prototype 轉成可 review、可驗證、可追溯的前端實作依據。

目前只保留新 MVP 有價值的功能：

```text
doctor -> scan
```

## 目前 MVP 狀態

已完成：

- `ht doctor`
- `ht scan`
- `ht.config.js/json/ts/mjs` 設定載入
- Vite static server
- Playwright full-page screenshot
- DOM summary artifact
- accessibility tree artifact
- browser resource failure metadata
- `.ht/cache/prototype`
- `.ht/spec/*.spec.json`
- `.ht/spec/*.validation.json`
- `.ht/spec/*.ui-contract.md`
- 頁面級 `pageContract`
- 基本 E2E 測試

刻意不保留：

- `ht plan`
- `ht run`
- `ht diff`
- `ht verify`
- `ht go`
- `ht status`
- Stage 2 decomposition
- TaskList
- output renderer
- visual similarity scoring
- coding agent invocation

不要重新加入未完成的 pipeline 骨架。只有在使用者明確要求某個能力，且需求足夠具體時才新增。

## 套件管理

使用 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。

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

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

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

安裝瀏覽器：

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

## 預設資料夾

預設 config：

```text
packages/prototype   # HTML prototype
.ht                  # tool artifacts
```

本 repo 根目錄可用 `ht.config.mjs` 把 prototype 指到 `./prototype`。

## 開發原則

- 保持 MVP 邊界，只保留 `doctor` 與 `scan` 的實際價值。
- 不要把 placeholder 包裝成完整實作。
- 不要新增未完成 command。
- Stage 2 decomposition 目前不做。
- 每個輸出 artifact 都要能重跑與人工 review。
- 不修改 `prototype/` 原始輸入資料夾。
- 產物只寫入 `.ht/`。

## 驗證

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

```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
```

## 重要檔案

- `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/doctor.js`：前置檢查。
- `src/stages/scan.js`：capture、page contract、validation。
- `test/cli-e2e.test.js`：doctor/scan E2E 測試。

## 下一個方向

下一個有價值的方向是改善 `pageContract` 品質，例如更準確的 form label、table header、action 分類與 evidence warning。不要先做 TaskList 或自動寫 code。