Orchestrate engine-bridge v2 + smoke test guide (#10)

- Plugin masquerade pass (11 tests), drop-in via HmEG.PluginLoader (no MEF) - Smoke test guide covers recorder/player/runner/plugin end-to-end manual steps - PROGRESS.md Done rows, PLAN.md pivoted to v3 reflection mapping Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-07 16:12:59 +09:00
parent b1c2383a54
commit a0609f8f0e
6 changed files with 345 additions and 7 deletions
--- a/docs/contracts/engine-bridge-v2.evaluation.md
+++ b/docs/contracts/engine-bridge-v2.evaluation.md
@@ -0,0 +1,41 @@
+# engine-bridge v2 — Evaluation
+
+**Verdict:** PASS
+**Generator commit:** b1c2383
+**Evaluator:** independent eval pass, 2026-04-07
+**Issue:** #10
+
+## DoD verdict table
+
+| # | DoD item | Result | Evidence |
+|---|---|---|---|
+| 1 | `dotnet build recordingtest.sln` green | PASS | 0 warnings, 0 errors, 6.55s |
+| 2 | Integration tests = 6 pass | PASS | `Recordingtest.EngineBridge.IntegrationTests` 6/6 in 687 ms |
+| 3 | EgPlugin tests >= 3 pass | PASS | `Recordingtest.EgPlugin.Tests` 5/5 (exceeds claim of 5) |
+| 4 | csproj: net8.0-windows + HintPath to EG-BIM Modeler/, Private=false, no local copy | PASS | csproj L3, L11-19; no DLL copies under `src/` |
+| 5 | HmEgBridgePlugin: inherits EditorPlugin, overrides Name/Description/Initialize, ctor boots listener, Dispose closes it | PASS | `HmEgBridgePlugin.cs` L10-47 |
+| 6 | StateRouter: 5 endpoints, 404 for unknown, try/catch -> `{"error":...}` | PASS | `StateRouter.cs` L28-42 |
+| 7 | PortResolver: env var `RECORDINGTEST_BRIDGE_PORT`, default 38080, safe parse | PASS | `PortResolver.cs` L5-17 (also bounds-checks 1..65535) |
+| 8 | HmEgHttpSnapshot: IEngineSnapshot impl, GET per property, 2s default timeout w/ ctor override, throws EngineBridgeException | PASS | `HmEgHttpSnapshot.cs` L13-107 |
+| 9 | Tests meaningful (FakeBridgeServer + real client; pure-logic plugin tests) | PASS | `FakeBridgeServer.cs`, `HmEgHttpSnapshotTests.cs`, `StateRouterTests.cs` |
+| 10 | deploy guide: Build/Copy/Env/Launch/Verify/Troubleshoot/Uninstall + SUT-write warning | PASS | `docs/guides/engine-bridge-deploy.md` sec 1-7, warning in sec 2 |
+| 11 | No writes to `EG-BIM Modeler/` from src | PASS | grep finds only csproj read-only HintPaths |
+| 12 | No copy of `Editor03.PluginInterface.dll` / `HmEG.dll` in `src/` | PASS | glob returns 0 matches |
+
+## Notes
+
+- `ReflectionEngineStateProvider` is a skeleton returning defaults. Contract
+  explicitly allows this ("진짜 매핑은 smoke test 후 조정"). Graded PASS with
+  note — production mapping deferred to v3 post-smoke.
+- StateRouter returns HTTP 200 for provider-thrown errors with `{"error":"..."}`
+  payload (per contract spec line 22). Acceptable per DoD wording.
+- BridgeHttpServer swallows listener errors so SUT stability is preserved
+  (port-conflict path handled).
+- EgPlugin test count is 5, exceeding the contract minimum of 3.
+
+## Artifacts
+
+- src: `src/Recordingtest.EgPlugin/`, `src/Recordingtest.EngineBridge.Client/`
+- tests: `tests/Recordingtest.EngineBridge.IntegrationTests/`, `tests/Recordingtest.EgPlugin.Tests/`
+- guide: `docs/guides/engine-bridge-deploy.md`
+- history: `docs/history/2026-04-07_이슈10-engine-bridge-v2-evaluator.md`
--- a/docs/guides/smoke-test.md
+++ b/docs/guides/smoke-test.md
@@ -0,0 +1,232 @@
+# 라이브 SUT Smoke Test 가이드
+
+이 문서는 recordingtest의 5개 PoC 모듈을 **실제 EG-BIM Modeler** 위에서 E2E로 검증하는 수동 절차다. 샌드박스 환경에서는 실행 불가 — 실제 Windows 워크스테이션에서 사용자가 직접 수행한다.
+
+## 목적
+
+다음 PoC의 DoD 중 "라이브 SUT 필수" 항목을 확인한다:
+- recorder #1: console attach + Win32 hook capture
+- recorder #7: 60 FPS 성능
+- player #2: `wait_for` UIA 이벤트 동작
+- player #7: 동일 시나리오 10회 중 9회 성공
+- test-runner: 실 시나리오 → normalize → diff 파이프라인
+- engine-bridge v2: HttpListener 플러그인 로드 + `/health` 응답
+
+## 사전 준비
+
+### 1. 환경
+- Windows 10/11 대화형 세션 (세션 0 불가)
+- .NET SDK 8 또는 9 (`dotnet --info` 확인)
+- `EG-BIM Modeler/` 폴더가 repo root 하위에 존재 (git 제외 대상)
+- 고정 DPI 권장 (100% 또는 150% 일관)
+- 관리자 권한은 `HttpListener` urlacl 이슈 시에만 필요
+
+### 2. 빌드
+```powershell
+cd d:\MYCLAUDE_PROJECT\recordingtest
+dotnet build recordingtest.sln
+dotnet test
+```
+**기대**: 전체 green, 42+ 테스트 통과.
+
+### 3. 시나리오/베이스라인 디렉터리 준비
+```powershell
+mkdir scenarios baselines artifacts
+```
+
+---
+
+## Step 1 — recorder 수동 캡처
+
+### 1a. SUT 실행
+`EG-BIM Modeler\EG-BIM Modeler.exe` 를 더블클릭하거나:
+```powershell
+& ".\EG-BIM Modeler\EG-BIM Modeler.exe"
+```
+메인 창이 뜰 때까지 대기.
+
+### 1b. recorder attach
+새 터미널에서:
+```powershell
+dotnet run --project src\Recordingtest.Recorder -- `
+  --output scenarios\box-create.yaml `
+  --attach "EG-BIM Modeler"
+```
+콘솔에 "attached" 메시지 확인.
+
+### 1c. 수동 테스트 동작
+메인 창에서 다음 수행:
+1. `Box` 명령 실행 (리본/툴바/커맨드 라인)
+2. 첫 번째 코너 클릭
+3. 두 번째 코너 클릭
+4. 높이 입력 후 Enter
+5. 파일 → 저장 → `artifacts\manual-box.hme`
+
+### 1d. recorder 종료
+터미널에서 `Ctrl+C`. 요약 출력 확인:
+- 캡처된 이벤트 수
+- 미해결 uia_path 수
+- 소요 시간
+
+### 1e. 산출물 확인
+```powershell
+Get-Content scenarios\box-create.yaml
+```
+- 클릭·드래그·키 이벤트가 기록됐는지
+- `uia_path` 가 유의미한 값인지 (3D 뷰포트 클릭은 호스팅 WPF 컨트롤 경로)
+- `offset_norm` 이 `[0..1]` 범위
+- `PasswordBox` 있으면 `<MASKED>` 처리
+
+**Smoke 체크리스트**:
+- [ ] recorder가 attach 성공
+- [ ] Ctrl+C 후 yaml 파일 생성
+- [ ] 이벤트 수 ≥ 5
+- [ ] SUT 정상 종료
+
+---
+
+## Step 2 — player 재생
+
+### 2a. baseline 저장
+첫 성공 수행 시 저장된 `manual-box.hme` 를 베이스라인으로 승격:
+```powershell
+Copy-Item artifacts\manual-box.hme baselines\box-create.approved.hme
+```
+
+### 2b. SUT 재시작 (깨끗한 상태)
+EG-BIM Modeler 를 완전히 종료 후 다시 실행.
+
+### 2c. player 실행
+```powershell
+dotnet run --project src\Recordingtest.Player -- `
+  --scenario scenarios\box-create.yaml `
+  --output-dir artifacts\replay `
+  --no-launch
+```
+
+**Smoke 체크리스트**:
+- [ ] player가 SUT에 attach
+- [ ] Box 명령이 실제로 실행되는 것이 화면에 보임
+- [ ] exit code 0
+- [ ] `artifacts\replay\` 에 결과 파일 존재
+- [ ] 고정 sleep 없이 동작 (UIA 대기 기반)
+
+### 2d. 10회 reliability (player DoD #7)
+```powershell
+for ($i=1; $i -le 10; $i++) {
+    dotnet run --project src\Recordingtest.Player -- `
+      --scenario scenarios\box-create.yaml `
+      --output-dir "artifacts\replay-$i" `
+      --no-launch
+    if ($LASTEXITCODE -ne 0) { "Run $i FAILED" }
+}
+```
+**기대**: 9회 이상 exit 0. 실패 케이스는 `artifacts\replay-N\error.log` 확인.
+
+---
+
+## Step 3 — test-runner E2E 파이프라인
+
+### 3a. 여러 시나리오 등록
+Step 1을 반복해 최소 2~3개 yaml 생성 (예: `box-create.yaml`, `circle-draw.yaml`).
+
+### 3b. 러너 실행
+```powershell
+dotnet run --project src\Recordingtest.Runner -- `
+  --scenarios scenarios `
+  --baselines baselines `
+  --out artifacts\regression-run `
+  --profile default
+```
+
+### 3c. 리포트 확인
+```powershell
+Get-Content artifacts\regression-run\report.md
+Get-Content artifacts\regression-run\report.json | ConvertFrom-Json
+```
+
+**Smoke 체크리스트**:
+- [ ] 모든 시나리오 `pass`
+- [ ] `report.json` 스키마 정상 (`runAt`, `total`, `passed`, `failed`, `errored`, `scenarios[]`)
+- [ ] `report.md` 표 렌더링 정상
+- [ ] 고의로 baseline 1바이트 바꿔 재실행 → `fail` + hunk 리포트 확인
+
+---
+
+## Step 4 — engine-bridge v2 플러그인 배포
+
+### 4a. 플러그인 빌드
+```powershell
+dotnet publish src\Recordingtest.EgPlugin -c Release -o publish\EgPlugin
+```
+
+### 4b. SUT Plugins 폴더에 복사 (사용자 수동)
+⚠ `EG-BIM Modeler/` 는 `guard-sut-folder.sh` hook이 Claude의 자동 쓰기를 차단한다. **사용자가 직접** PowerShell로 복사:
+```powershell
+$dest = ".\EG-BIM Modeler\Plugins\Recordingtest.EgPlugin"
+mkdir $dest -Force
+Copy-Item publish\EgPlugin\Recordingtest.EgPlugin.dll $dest
+```
+`Editor03.PluginInterface.dll` 과 `HmEG.dll` 은 복사하지 않는다 (SUT 정본 사용).
+
+### 4c. 환경변수 (선택)
+```powershell
+$env:RECORDINGTEST_BRIDGE_PORT = "38080"
+```
+
+### 4d. SUT 실행
+`EG-BIM Modeler.exe` 시작. 플러그인 로더가 `Recordingtest.EgPlugin.dll` 을 자동 발견.
+
+### 4e. `/health` 확인
+```powershell
+curl http://localhost:38080/health
+```
+**기대**: `{"status":"ok","port":38080}`
+
+### 4f. 상태 엔드포인트
+```powershell
+curl http://localhost:38080/selection
+curl http://localhost:38080/camera
+curl http://localhost:38080/scene
+curl http://localhost:38080/render
+```
+v2는 ReflectionEngineStateProvider가 skeleton이라 기본값 또는 `{"error": ...}` 반환 가능. 이후 **v3에서 실매핑** 예정.
+
+### 4g. 언인스톨
+```powershell
+Remove-Item .\EG-BIM Modeler\Plugins\Recordingtest.EgPlugin -Recurse
+```
+
+**Smoke 체크리스트**:
+- [ ] 플러그인 dll이 SUT에 로드 (로그 확인: `EG-BIM Modeler\hmlogs\` 또는 `Log\`)
+- [ ] `/health` 200 OK
+- [ ] 포트 충돌 없음
+- [ ] SUT 정상 종료 시 listener 해제
+
+---
+
+## 실패 시 트러블슈팅
+
+| 증상 | 원인 후보 | 조치 |
+|------|-----------|------|
+| recorder attach 실패 | 창 제목 mismatch | `--attach` 값을 정확한 제목 또는 PID로 |
+| player uia_path 탐색 실패 | 해상도/DPI 변경 | baseline 당시와 동일 DPI 고정 |
+| 10회 중 실패 다수 | plugin 로드 지연 | scenario 첫 step에 `wait_for` 추가 |
+| report 바이너리 diff 많음 | normalizer 규칙 미흡 | `docs/contracts/normalizer.md` follow-up 반영 |
+| 플러그인 미로드 | dll 경로/버전 mismatch | `hmlogs`에서 로더 메시지 확인 |
+| `/health` 연결 거부 | HttpListener urlacl | 관리자 권한 실행 or `netsh http add urlacl` |
+
+## 결과 보고
+
+Smoke test 완료 후:
+1. 각 체크리스트 결과 수집
+2. 실패 항목은 `docs/history/YYYY-MM-DD_smoke-test.md` 에 기록 (소요 시간, Context 사용량 포함)
+3. 10회 재생 reliability 수치 → player DoD #7 update
+4. 이슈 #2 또는 새 이슈에 리포트 코멘트
+
+## v3 이후 과제
+
+- recorder IME 조합 키 처리
+- player full ancestor chain uia_path resolver
+- engine-bridge ReflectionEngineStateProvider 실매핑 (HmEG 내부 타입 접근)
+- normalizer `mask_volatile_settings` JSON-path 스코핑
--- a/docs/history/2026-04-07_이슈10-engine-bridge-v2-evaluator.md
+++ b/docs/history/2026-04-07_이슈10-engine-bridge-v2-evaluator.md
@@ -0,0 +1,29 @@
+# 이슈 #10 — engine-bridge v2 Evaluator
+
+- 일자: 2026-04-07
+- 역할: Evaluator (독립 평가)
+- 대상 commit: b1c2383
+- 소요 시간: 약 6분 (build 7s + tests 1s + 리뷰)
+- Context 사용량 힌트: 약 35K 토큰 (대부분 source/test/contract 읽기)
+- 결과: **PASS**
+
+## 검증 절차
+
+1. `dotnet build recordingtest.sln` -> 0 warn / 0 err
+2. `dotnet test tests/Recordingtest.EngineBridge.IntegrationTests` -> 6/6
+3. `dotnet test tests/Recordingtest.EgPlugin.Tests` -> 5/5
+4. csproj 리뷰: net8.0-windows, HintPath `..\..\EG-BIM Modeler\`, `<Private>false</Private>`
+5. `HmEgBridgePlugin.cs` 리뷰: EditorPlugin 상속, ctor에서 listener boot, Dispose 정리
+6. `StateRouter.cs` 리뷰: 5 엔드포인트 + 404 + try/catch error payload
+7. `PortResolver.cs` 리뷰: env `RECORDINGTEST_BRIDGE_PORT`, default 38080, 범위 검증
+8. `HmEgHttpSnapshot.cs` 리뷰: 2초 timeout, ctor override, EngineBridgeException 변환
+9. 테스트 진정성: FakeBridgeServer 기반 round-trip + 순수 로직 plugin tests
+10. deploy 가이드 7개 섹션 + SUT 폴더 쓰기 경고 확인
+11. grep `EG-BIM Modeler` in src/Recordingtest.EgPlugin -> csproj HintPath만, 쓰기 없음
+12. `Editor03.PluginInterface.dll` / `HmEG.dll` 가 `src/`에 복사되지 않음 확인
+
+## 참고
+
+- ReflectionEngineStateProvider skeleton은 contract에서 명시적으로 허용 → PASS with note
+- StateRouter가 provider 예외 시 HTTP 200 + `{"error":...}` 페이로드 반환 (contract L22 부합)
+- 산출물: `docs/contracts/engine-bridge-v2.evaluation.md`
--- a/docs/history/2026-04-07_이슈10-engine-bridge-v2-orchestration.md
+++ b/docs/history/2026-04-07_이슈10-engine-bridge-v2-orchestration.md
@@ -0,0 +1,38 @@
+# 2026-04-07 이슈 #10 — engine-bridge v2 오케스트레이션 + smoke test 가이드
+
+- **이슈**: #10 (engine-bridge v2)
+- **소요 시간**: ~15분 (Generator/Evaluator 백그라운드 + 가이드 문서 작성)
+- **Context 사용량**: ~290k tokens (orchestrator 누적)
+
+## 사이클
+
+1. Planner 역할로 `docs/contracts/engine-bridge-v2.md` 작성
+2. 이슈 #10 생성
+3. Generator 백그라운드 → commit `b1c2383`
+4. Evaluator 백그라운드 → **pass** (12/12 DoD)
+5. `docs/guides/smoke-test.md` 작성 (2단계)
+6. PROGRESS/PLAN 갱신, 이슈 #10 close
+
+## 주요 발견 (Editor03 discovery)
+
+- **SUT가 MEF가 아닌 자체 PluginLoader 사용** — `[Export]` 속성 불필요, 단순 drop-in
+- `HmEG.IPlugin` 실제 계약, `EditorPlugin` 추상 베이스
+- `EgBoxPlugin` 샘플로 확인됨 → 배포 난이도 낮음
+- MetadataLoadContext에 `WindowsDesktop.App.Ref` 팩 필요
+
+## 산출물
+
+- `src/Recordingtest.EgPlugin/` — 플러그인 dll (HttpListener + 5 endpoints)
+- `src/Recordingtest.EngineBridge.Client/` — HmEgHttpSnapshot HTTP 클라이언트
+- `tests/Recordingtest.EngineBridge.IntegrationTests/` — 6 tests (fake HttpListener)
+- `tests/Recordingtest.EgPlugin.Tests/` — 5 tests (pure logic)
+- `docs/guides/engine-bridge-deploy.md` — 플러그인 배포
+- `docs/guides/smoke-test.md` — 5-모듈 E2E 수동 검증 절차 (Step 1~4)
+
+## 비용
+
+Generator ~93k + Evaluator ~38k + Orchestrator ~20k = **~151k**
+
+## 다음 단계
+
+3단계(정리)로 진행 — 현재 상태 총괄 리포트.