## 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 以上。

```bash
node --version
```

### 2. 安裝專案相依套件

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

```bash
pnpm install
```

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

```bash
npx --no-install playwright-cli --version
```

或透過 npm script：

```bash
pnpm playwright-cli -- --version
```

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

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

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

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

### 3. 準備資料夾

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

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

最小可跑範例：

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

新增一個 prototype：

```html
<!-- 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` 時會使用預設值。若要覆寫路徑或關閉互動確認，可以建立：

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

```ts
import { defineConfig } from 'html-transform'

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

### 5. 檢查環境

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

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

產出：

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

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

產出：

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

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

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

```text
packages/result/index/main-1.vue
```

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

```text
.ht/runs/<runId>/
```

若只想重跑失敗 task：

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

### 9. 產生 diff report

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

產出：

```text
.ht/diff/*.diff.html
```

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

### 10. 執行驗證

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

產出：

```text
.ht/verify/verification-report.json
```

驗證包含：

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

### 11. 一次跑完整流程

```bash
node src/cli.js go --yes
```

等同依序執行：

```bash
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 狀態

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

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

## 開發驗證

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

## 常用指令摘要

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