html-transform/README.md

A prototype-driven orchestration framework for CLI coding agents in TypeScript monorepos

• prototype-driven：不是純 spec，也不是純 code-first。
• orchestration framework：主體是 workflow 與 gates，不是模型本身。
• CLI coding agents：Claude Code、Codex、Gemini 只是 adapter targets，不是核心。

MVP

這個版本提供一個可執行的 ht CLI 骨架，依照 PRD 的 stage 產出可 review 的中間 artifact：

• ht scan：讀取 prototype/ HTML，產生 .ht/cache/prototype/、.ht/spec/*.spec.json、ui-contract.md
• ht plan：掃描 frontend/backend，產生 .ht/plan/tasklist.json、conventions、API contract、component mapping
• ht run：依 TaskList 產生 Vuetify .vue 檔到 output/
• ht diff：產生 .ht/diff/*.diff.html
• ht verify：執行 quality commands 並產生 .ht/verify/verification-report.json
• ht go --yes：串起完整流程

外部 vision/agent/Playwright 尚未假裝成已整合；目前以 deterministic HTML evidence 建立 MVP artifact，缺少的執行環境會在 report 或 ht doctor 中明確標示。

使用方式

1. 確認 Node 版本

需要 Node.js 20 以上。

node --version

2. 安裝專案相依套件

建議使用專案級安裝，不依賴全域 playwright-cli：

pnpm install

本專案使用 @playwright/cli，指令名稱是 playwright-cli。安裝後可以用：

npx --no-install playwright-cli --version

或透過 npm script：

pnpm playwright-cli -- --version

若環境還沒有瀏覽器 binary，先安裝預設瀏覽器：

pnpm playwright-cli:install-browser

Linux CI 或乾淨容器可能還需要系統套件，先用 dry-run 看會做什麼：

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

3. 準備資料夾

預設設定會讀取以下路徑：

packages/
├── prototype/   # 放 HTML prototype
├── web/         # 既有 Vuetify frontend 專案
├── api/         # backend API 或 schema
└── result/      # 產生結果

最小可跑範例：

mkdir -p packages/prototype packages/web/src packages/api packages/result

新增一個 prototype：

<!-- packages/prototype/index.html -->
<main>
  <h1>Customer Portal</h1>
  <form>
    <label>Email</label>
    <input name="email" required>
    <button>Submit</button>
  </form>
</main>

4. 選擇性建立設定檔

沒有 ht.config.js 時會使用預設值。若要覆寫路徑或關閉互動確認，可以建立：

// ht.config.js
export default {
  prototype: './packages/prototype',
  frontend: './packages/web',
  backend: './packages/api',
  output: './packages/result',
  agent: 'codex',
  plan: {
    interactiveReview: false,
    requireApiContractMatch: true
  },
  project: {
    qualityCommands: {
      typecheck: 'pnpm typecheck',
      lint: 'pnpm lint',
      test: 'pnpm test'
    }
  }
}

也可以使用 ht.config.ts：

import { defineConfig } from 'html-transform'

export default defineConfig({
  prototype: './packages/prototype',
  frontend: './packages/web',
  backend: './packages/api',
  output: './packages/result'
})

5. 檢查環境

node src/cli.js doctor

doctor 會檢查 prototype/frontend/backend/output parent、playwright-cli、agent CLI、pnpm 是否存在。缺少項目會標示為 missing。

playwright-cli 的偵測順序：

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

6. 執行 scan

node src/cli.js scan

產出：

.ht/cache/prototype/
.ht/spec/*.spec.json
.ht/spec/*.validation.json
.ht/spec/*.ui-contract.md

這一步會從 HTML 擷取 DOM summary、accessibility-like tree、region、LayoutSpec 與 UI contract。MVP 目前使用 deterministic HTML evidence；截圖檔是 placeholder PNG。

後續接真實 browser automation 時，會透過 playwright-cli shell 指令操作，不透過 MCP。

7. 產生 TaskList

node src/cli.js plan

產出：

.ht/plan/tasklist.json
.ht/plan/project-conventions.md
.ht/plan/api-contract.md
.ht/plan/component-mapping.json

若 plan.interactiveReview 設為 true，CLI 會在產生 TaskList 後要求輸入 y 才繼續。

8. 產生 output

node src/cli.js run

產出會寫入 output 設定的資料夾，例如：

packages/result/index/main-1.vue

每個 task 的執行記錄會寫入：

.ht/runs/<runId>/

若只想重跑失敗 task：

node src/cli.js run --retry-failed

9. 產生 diff report

node src/cli.js diff

產出：

.ht/diff/*.diff.html

MVP 目前會建立可 review 的 HTML report 結構；真實 playwright-cli 截圖與 vision similarity scoring 尚未串接。

10. 執行驗證

node src/cli.js verify

產出：

.ht/verify/verification-report.json

驗證包含：

• project.qualityCommands 中設定的 typecheck/lint/test
• output target 是否存在
• flow checks 目前在 MVP 中會標示為 skipped

11. 一次跑完整流程

node src/cli.js go --yes

等同依序執行：

node src/cli.js scan
node src/cli.js plan
node src/cli.js run
node src/cli.js diff
node src/cli.js verify

12. 查看 task 狀態

node src/cli.js status

會顯示 pending、running、done、error 的 task 數量。

開發驗證

pnpm test
pnpm typecheck

目前 MVP 限制

• 尚未整合 Playwright static server、真實 full-page screenshot、DOM snapshot API 與 accessibility tree API。
• Playwright 操作會以 playwright-cli shell command 為準，不使用 MCP；目前已加入專案級 @playwright/cli 安裝與環境偵測。
• 尚未真的呼叫 Claude Code/Codex/Gemini 進行 vision decomposition 或 coding task。
• diff 的 similarity score 目前是 deterministic report placeholder，不是 vision scoring。
• run 目前以 LayoutSpec 產生基本 Vuetify Vue component，還不是完整專案級整合。
• 缺少 quality command 或外部工具時，會在 report 或 doctor 中標示為 skipped/missing。

常用指令摘要

pnpm test
pnpm typecheck
node src/cli.js doctor
node src/cli.js scan
node src/cli.js plan
node src/cli.js run
node src/cli.js diff
node src/cli.js verify