diff --git a/PLAN.md b/PLAN.md index 25daac2..31212d2 100644 --- a/PLAN.md +++ b/PLAN.md @@ -8,14 +8,10 @@ 1. **훅 동작 검증** — SessionStart/Stop/Guard 3개 shell 스크립트를 실제로 트리거시켜 확인 - 의존: jq 설치 여부 확인 -## P1 — 라이브 검증 & 런타임 엔진 접근 +## P1 — 라이브 검증 (사용자 환경 필요) -4. **라이브 SUT smoke test** — 사용자 환경에서 recorder/player/runner 실제 검증 (E2E) - - 의존: 없음 - - 가이드: `docs/guides/smoke-test.md` (작성 필요) -5. **engine-bridge v2** — MEF plugin masquerade 구현 (design doc 권고) - - 의존: engine-bridge v1 (완료) - - 범위: 커스텀 MEF plugin이 HmEG 상태를 로컬 HTTP/named pipe로 노출 → recordingtest가 수집 +4. **라이브 SUT smoke test 실행** — `docs/guides/smoke-test.md` 따라 수동 수행 +5. **engine-bridge v3** — ReflectionEngineStateProvider 실매핑 (smoke test 이후) ## Follow-ups (non-blocking) diff --git a/PROGRESS.md b/PROGRESS.md index 7159712..fa6eef7 100644 --- a/PROGRESS.md +++ b/PROGRESS.md @@ -33,6 +33,8 @@ | 2026-04-07 | recorder PoC + Evaluator pass v2 (#6) — drag state machine, focus events, ts/raw_coord | `src/Recordingtest.Recorder/`, `docs/contracts/recorder.evaluation.md` | | 2026-04-07 | test-runner PoC + Evaluator pass (#8) — 5-module E2E 파이프라인, 6 tests, DI | `src/Recordingtest.Runner/`, `docs/contracts/test-runner.evaluation.md` | | 2026-04-07 | engine-bridge PoC v1 + Evaluator pass (#9) — 정적 분석, HmEG 내부 후보 8000+, API 초안 | `src/Recordingtest.EngineBridge*/`, `docs/engine-catalog/`, `docs/engine-bridge-probe-design.md` | +| 2026-04-07 | engine-bridge v2 + Evaluator pass (#10) — MEF plugin masquerade, HttpListener, HmEgHttpSnapshot, 11 tests | `src/Recordingtest.EgPlugin/`, `src/Recordingtest.EngineBridge.Client/`, `docs/guides/engine-bridge-deploy.md` | +| 2026-04-07 | 라이브 SUT smoke test 가이드 작성 | `docs/guides/smoke-test.md` | ## In progress diff --git a/docs/contracts/engine-bridge-v2.evaluation.md b/docs/contracts/engine-bridge-v2.evaluation.md new file mode 100644 index 0000000..89eb7bc --- /dev/null +++ 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` diff --git a/docs/guides/smoke-test.md b/docs/guides/smoke-test.md new file mode 100644 index 0000000..b496b42 --- /dev/null +++ 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` 있으면 `` 처리 + +**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 스코핑 diff --git a/docs/history/2026-04-07_이슈10-engine-bridge-v2-evaluator.md b/docs/history/2026-04-07_이슈10-engine-bridge-v2-evaluator.md new file mode 100644 index 0000000..bb47964 --- /dev/null +++ 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\`, `false` +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` diff --git a/docs/history/2026-04-07_이슈10-engine-bridge-v2-orchestration.md b/docs/history/2026-04-07_이슈10-engine-bridge-v2-orchestration.md new file mode 100644 index 0000000..fc4b5a4 --- /dev/null +++ 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단계(정리)로 진행 — 현재 상태 총괄 리포트.