@walwal-harness/cli 2.4.0 → 3.2.0

package/skills/generator-frontend-flutter/references/anti-patterns.md

@@ -33,26 +33,49 @@ docmeta:
 
 각 항목은 **패턴 → 이유 → 대체 방법** 형태.
 
-## 1. 웹 전용 API 직접 참조
+## 1. 웹 전용 API 직접 참조 (fe_target 별 차이)
 
-### 금지
+### `fe_target = mobile` 또는 `desktop` — 금지
 ```dart
-import 'dart:html';
-import 'package:universal_html/html.dart';
+import 'dart:html';                              // ✗
+import 'package:universal_html/html.dart';       // ✗
+import 'package:web/web.dart';                   // ✗ (가드 없으면)
 ```
 
 ### 이유
-Flutter 앱은 크로스 플랫폼 — 모바일 빌드에서 `dart:html` 참조는 즉시 빌드 실패한다.
-Web 빌드 전용 코드가 필요하면 조건부 import 패턴을 사용한다.
+Flutter 모바일/데스크톱 빌드에서 `dart:html` 참조는 즉시 빌드 실패한다.
+가드 없이 import 하면 cross-platform 코드가 깨진다.
 
 ### 대체
-`package:web` 또는 `kIsWeb` 분기로 플랫폼 체크 후 조건부 import.
+- `kIsWeb` 분기로 플랫폼 체크 후 조건부 import
+- `if (kIsWeb) { ... }` 가드 안에서만 web API 사용
+- 또는 conditional import (`stub.dart` / `web.dart` / `io.dart`)
+
+### `fe_target = web` — 허용 (단, 권장 패턴 준수)
+```dart
+import 'package:web/web.dart' as web;            // ✓ 권장 (modern)
+import 'dart:js_interop';                        // ✓ JS interop
+import 'dart:html';                              // ✓ (legacy, 신규 코드는 package:web 권장)
+```
+
+### Web 권장 패턴
+- 새 코드는 `package:web` + `dart:js_interop` 사용 (Flutter 3.7+ 에서 stable)
+- `dart:html` 은 legacy — 마이그레이션 대상이지만 즉시 금지는 아님
+- 가능하면 web 전용 코드를 별도 파일로 분리하고 conditional import:
+  ```dart
+  // _web_helper.dart 또는 conditional import
+  import 'platform_helper.dart'
+    if (dart.library.html) 'platform_helper_web.dart'
+    if (dart.library.io) 'platform_helper_io.dart';
+  ```
 
 ### 검증
 ```bash
-grep -rn "dart:html\|universal_html" lib/ integrated_data_layer/lib/
+# fe_target = mobile/desktop: 0개여야 함
+grep -rn "dart:html\|universal_html\|package:web" lib/ integrated_data_layer/lib/
+
+# fe_target = web: 매치 OK, 단 'kIsWeb' 가드 또는 conditional import 와 함께 쓰는지 인접 라인 확인
 ```
-결과 0개여야 함.
 
 ---
 
@@ -263,11 +286,20 @@ grep -rEn "(api[_-]?key|secret|token)\s*=\s*['\"][A-Za-z0-9]{16,}['\"]" lib/ int
 
 ## 셀프 체크 스크립트
 
-Generator는 handoff 전 다음 명령을 모두 실행하고 결과를 sprint-contract.md에 기록한다:
+Generator는 handoff 전 다음 명령을 모두 실행하고 결과를 sprint-contract.md에 기록한다.
+**`fe_target` 에 따라 1번 룰의 적용 여부가 달라진다.**
 
 ```bash
-# 1. 웹 API 직접 참조
-grep -rn "dart:html\|universal_html" lib/ integrated_data_layer/lib/ || echo "OK"
+# fe_target 읽기
+FE_TARGET=$(jq -r '.fe_target // "web"' .harness/actions/pipeline.json 2>/dev/null || echo "web")
+
+# 1. 웹 API 직접 참조 — fe_target=web 이 아닐 때만 검사
+if [ "$FE_TARGET" != "web" ]; then
+  grep -rn "dart:html\|universal_html\|package:web" lib/ integrated_data_layer/lib/ || echo "OK (FL-01 mobile/desktop)"
+else
+  # web 타겟: 가드 없는 사용만 경고 (수동 검토)
+  grep -rn "dart:html\|package:web" lib/ | grep -v "kIsWeb\|conditional import" || echo "OK (FL-01 web — manual review)"
+fi
 
 # 2. print 남발
 grep -rn "^\s*print(" lib/ integrated_data_layer/lib/ || echo "OK"

package/skills/generator-frontend-flutter/references/flutter-web-pattern.md

@@ -0,0 +1,273 @@
+---
+docmeta:
+  id: flutter-web-pattern
+  title: Flutter Web 패턴 — fe_target=web 전용
+  type: output
+  createdAt: 2026-04-09T00:00:00Z
+  updatedAt: 2026-04-09T00:00:00Z
+  source:
+    producer: agent
+    skillId: harness-generator-frontend-flutter
+  inputs:
+    - documentId: harness-generator-frontend-flutter-skill
+      uri: ../SKILL.md
+      relation: output-from
+      sections:
+        - sourceRange:
+            startLine: 56
+            endLine: 90
+          targetRange:
+            startLine: 21
+            endLine: 240
+    - documentId: flutter-anti-patterns
+      uri: ./anti-patterns.md
+      relation: output-from
+      sections:
+        - sourceRange:
+            startLine: 22
+            endLine: 75
+          targetRange:
+            startLine: 90
+            endLine: 165
+  tags:
+    - flutter
+    - flutter-web
+    - dart-web
+    - go-router
+---
+
+# Flutter Web 패턴 (`fe_target = web` 전용)
+
+`pipeline.json.fe_target == "web"` 일 때만 적용. Mobile/Desktop 타겟에서는 이 문서의 규칙을 무시한다.
+
+## 1. 프로젝트 활성화
+
+기존 Flutter 프로젝트에 Web 타겟이 없으면:
+
+```bash
+flutter config --enable-web
+flutter create --platforms=web .
+```
+
+`web/index.html`, `web/manifest.json`, `web/favicon.png`, `web/icons/` 가 생성된다.
+
+## 2. 빌드 및 개발 서버
+
+| 명령 | 용도 |
+|------|------|
+| `flutter run -d chrome` | 개발 서버 (HMR 포함) |
+| `flutter run -d chrome --web-port 8080` | 포트 고정 |
+| `flutter build web --release` | 프로덕션 빌드 (`build/web/`) |
+| `flutter build web --release --web-renderer canvaskit` | CanvasKit 렌더러 (성능 우선) |
+| `flutter build web --release --web-renderer html` | HTML 렌더러 (호환성 우선, 작은 번들) |
+
+> **렌더러 선택**: 모바일 사파리 호환성이 중요하면 `html`, 데스크톱/Chrome 중심이면 `canvaskit` (또는 auto).
+
+## 3. 라우팅 — `go_router` 권장
+
+URL 동기화 + 브라우저 history 지원을 위해 `go_router` 사용.
+
+```yaml
+# pubspec.yaml
+dependencies:
+  go_router: ^14.0.0
+```
+
+```dart
+// lib/router/app_router.dart
+import 'package:go_router/go_router.dart';
+
+final pAppRouterProvider = Provider<GoRouter>((ref) {
+  return GoRouter(
+    initialLocation: '/',
+    routes: [
+      GoRoute(path: '/', builder: (ctx, state) => const HomePage()),
+      GoRoute(path: '/login', builder: (ctx, state) => const LoginPage()),
+      GoRoute(
+        path: '/items/:id',
+        builder: (ctx, state) => ItemPage(id: state.pathParameters['id']!),
+      ),
+    ],
+  );
+});
+```
+
+```dart
+// main.dart
+class App extends ConsumerWidget {
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final router = ref.watch(pAppRouterProvider);
+    return MaterialApp.router(
+      routerConfig: router,
+      // ...
+    );
+  }
+}
+```
+
+**Hash routing vs Path routing**:
+- 기본은 hash routing (`/#/login`)
+- Path routing 으로 바꾸려면 `web/index.html` 의 `<base href="/">` 설정 + 서버 fallback (모든 경로 → `index.html`)
+
+## 4. JS Interop (필요할 때만)
+
+크로스플랫폼 코드를 우선하되, Web 전용 API 가 필요하면 `package:web` + `dart:js_interop` 사용.
+
+```dart
+import 'package:web/web.dart' as web;
+import 'dart:js_interop';
+
+void copyToClipboard(String text) {
+  web.window.navigator.clipboard.writeText(text.toJS);
+}
+
+String getUserAgent() => web.window.navigator.userAgent;
+```
+
+**Conditional import 패턴** (cross-platform 코드를 web/io 로 분기):
+
+```dart
+// platform_helper.dart (interface)
+abstract class PlatformHelper {
+  String get platformName;
+}
+
+PlatformHelper getPlatformHelper() => throw UnimplementedError();
+```
+
+```dart
+// platform_helper_web.dart
+import 'package:web/web.dart' as web;
+import 'platform_helper.dart';
+
+class WebPlatformHelper implements PlatformHelper {
+  @override
+  String get platformName => 'web (${web.window.navigator.userAgent})';
+}
+
+PlatformHelper getPlatformHelper() => WebPlatformHelper();
+```
+
+```dart
+// platform_helper_io.dart
+import 'dart:io';
+import 'platform_helper.dart';
+
+class IoPlatformHelper implements PlatformHelper {
+  @override
+  String get platformName => 'io (${Platform.operatingSystem})';
+}
+
+PlatformHelper getPlatformHelper() => IoPlatformHelper();
+```
+
+```dart
+// 사용처
+import 'platform_helper.dart'
+  if (dart.library.html) 'platform_helper_web.dart'
+  if (dart.library.io) 'platform_helper_io.dart';
+
+final helper = getPlatformHelper();
+print(helper.platformName);
+```
+
+## 5. CORS 와 백엔드 연동
+
+Flutter Web 은 브라우저에서 실행되므로 백엔드 API 호출 시 **CORS** 가 적용된다.
+
+- 개발 단계: 백엔드 Gateway 의 `Access-Control-Allow-Origin` 에 `http://localhost:8080` (또는 `*`) 추가
+- 프로덕션: 동일 origin 또는 명시적 CORS 화이트리스트
+- API 키/인증 토큰은 **HttpOnly cookie** 또는 메모리 보관 (localStorage 는 XSS 위험)
+
+`Dio` 인터셉터로 CSRF 토큰 등을 헤더에 추가:
+
+```dart
+final dio = Dio(BaseOptions(
+  baseUrl: 'https://api.example.com',
+  headers: {'Content-Type': 'application/json'},
+));
+
+dio.interceptors.add(InterceptorsWrapper(
+  onRequest: (options, handler) {
+    final token = ref.read(pAuthProvider).accessToken;
+    if (token != null) {
+      options.headers['Authorization'] = 'Bearer $token';
+    }
+    return handler.next(options);
+  },
+));
+```
+
+## 6. SEO / Meta Tags
+
+`web/index.html` 의 `<head>` 에 SEO 메타 태그 추가:
+
+```html
+<meta name="description" content="Suprema CLUe — Smart Access Control">
+<meta property="og:title" content="CLUe">
+<meta property="og:description" content="...">
+<meta property="og:image" content="/icons/og-image.png">
+<link rel="canonical" href="https://app.example.com">
+```
+
+> SPA 의 SEO 한계: Flutter Web 은 client-side rendering 이므로 검색엔진이 동적 콘텐츠를 인덱싱하지 못할 수 있다. SSR 이 필요하면 Next.js + REST API 패턴을 고려.
+
+## 7. 자산 최적화
+
+- 이미지: `assets/images/` 에 두고 `pubspec.yaml` 의 `flutter.assets` 에 등록
+- 폰트: `web/fonts/` 또는 `assets/fonts/` + `pubspec.yaml` 의 `flutter.fonts`
+- 큰 이미지: webp 사용 권장 (`flutter_image_compress` 또는 사전 변환)
+- Tree-shaking: `flutter build web --tree-shake-icons` 로 사용하지 않는 Material 아이콘 제거
+
+## 8. PWA (Progressive Web App)
+
+`flutter create --platforms=web` 시 자동 생성되는 `web/manifest.json` 을 채워서 PWA 로 동작:
+
+```json
+{
+  "name": "CLUe",
+  "short_name": "CLUe",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#FFFFFF",
+  "theme_color": "#6682FF",
+  "icons": [
+    { "src": "icons/Icon-192.png", "sizes": "192x192", "type": "image/png" },
+    { "src": "icons/Icon-512.png", "sizes": "512x512", "type": "image/png" }
+  ]
+}
+```
+
+Service worker 는 `flutter build web` 시 자동 생성된다 (`flutter_service_worker.js`).
+
+## 9. 디버깅 — Chrome DevTools
+
+- `flutter run -d chrome` 후 Chrome 자체 DevTools 열기 (F12)
+- Console 에서 `print()` 출력 확인 가능 (단, 프로덕션 빌드에서는 `print` 금지)
+- Source map 활성화: `--web-renderer html --source-maps` (디버그 빌드 기본)
+- Network 탭에서 API 호출 직접 검사 가능 → Playwright 기반 `evaluator-functional` 도 동일하게 동작
+
+## 10. Eval 인터페이스
+
+`fe_target = web` 인 경우 `harness-next.sh` 가 다음과 같이 자동 라우팅:
+
+```
+generator-frontend-flutter (Self-Verification: flutter analyze + flutter test)
+  → evaluator-functional (Playwright MCP — http://localhost:포트 E2E)
+  → evaluator-visual (Playwright MCP — 스크린샷 + 반응형 + 접근성)
+```
+
+**Generator 의 Self-Verification 단계에서 `flutter build web --release` 가 성공하는지 확인** 후 handoff.
+
+## 11. 호스팅 (참고)
+
+| 호스팅 | 빌드 산출물 |
+|--------|------------|
+| Vercel | `build/web/` 디렉토리를 정적 호스팅 |
+| Netlify | 동일 |
+| Firebase Hosting | `firebase deploy --only hosting` (firebase.json 의 public 을 `build/web` 으로) |
+| GitHub Pages | `build/web/` 을 gh-pages 브랜치에 푸시 |
+| 자체 서버 | nginx 로 정적 파일 서빙 + SPA fallback (`try_files $uri /index.html`) |
+
+호스팅 결정은 Planner / 사용자가 함. Generator 는 빌드 산출물만 보장.

package/skills/planner/references/fe-stack-detection.md

@@ -76,40 +76,87 @@ Planner는 Sprint 1 착수 전 반드시 `fe_stack`을 확정하고 `pipeline.js
 
 혼재 프로젝트(Web + Flutter mobile)라면 사용자에게 **현 스프린트의 타깃**을 묻는다 — 파이프라인은 한 번에 하나의 `fe_stack`만 취급한다.
 
+## 2.5 fe_target 확정 (Flutter 전용)
+
+`fe_stack == "flutter"` 인 경우, **반드시** `fe_target` 도 함께 확정해야 한다 (`web` | `mobile` | `desktop`).
+이는 Flutter Web vs Mobile/Desktop 에서 사용 가능한 API, 빌드 명령, evaluator 가 달라지기 때문이다.
+
+### 자동 감지 (scan-result.json 의 `tech_stack.fe_target`)
+
+| 시그널 | fe_target |
+|--------|-----------|
+| `<flutter_root>/web/index.html` 존재 | `web` |
+| `<flutter_root>/android/` 또는 `ios/` 존재, web/ 없음 | `mobile` |
+| `<flutter_root>/macos/`, `windows/`, `linux/` 존재 (mobile/web 없음) | `desktop` |
+| 없음 | `unknown` |
+
+### 사용자 질문 (불명확하거나 multi-target)
+
+```
+Flutter 프로젝트의 타깃을 확인합니다:
+
+(A) Web — 브라우저 (Chrome/Safari/Firefox), 컴파일 결과는 HTML+JS+CSS
+(B) Mobile — Android / iOS 네이티브 빌드
+(C) Desktop — macOS / Windows / Linux 네이티브 빌드
+
+감지된 시그널:
+- web/index.html: [있음/없음]
+- android|ios/: [있음/없음]
+- macos|windows|linux/: [있음/없음]
+
+이번 스프린트의 타깃은? (A/B/C)
+```
+
+### fe_target → Eval 흐름
+
+| fe_target | Generator | Eval-Functional | Eval-Visual |
+|-----------|-----------|----------------|-------------|
+| `web` | `generator-frontend-flutter` | `evaluator-functional` (Playwright!) | `evaluator-visual` (Playwright!) |
+| `mobile` | `generator-frontend-flutter` | `evaluator-functional-flutter` (정적 분석) | SKIP |
+| `desktop` | `generator-frontend-flutter` | `evaluator-functional-flutter` (정적 분석) | SKIP |
+
+**핵심**: Flutter Web 의 빌드 결과물(HTML/JS/CSS)은 일반 웹앱과 동일하므로 Playwright 기반
+React 경로의 evaluator 를 그대로 재사용한다. Generator-Frontend-Flutter 의 Self-Verification
+단계에서 `flutter analyze`/`flutter test`/`flutter build web` 정적 검증이 이미 통과한 상태로 handoff 된다.
+
 ## 3. pipeline.json 갱신
 
-`fe_stack` 확정 후 `pipeline.json`에 반드시 추가:
+`fe_stack` + `fe_target` 확정 후 `pipeline.json`에 반드시 추가:
 
 ```json
 {
   "pipeline": "FULLSTACK",
   "planner_mode": "full",
   "fe_stack": "flutter",
+  "fe_target": "web",
   "agents_active": [
     "planner",
     "generator-backend",
     "generator-frontend-flutter",
-    "evaluator-functional-flutter"
+    "evaluator-functional",
+    "evaluator-visual"
   ],
   "agents_skipped": [
     "generator-frontend",
-    "evaluator-functional",
-    "evaluator-visual"
+    "evaluator-functional-flutter"
   ],
-  "evaluator_mode": "flutter-native",
-  "notes": "Flutter 앱 — Playwright 대신 flutter analyze/test + 정적 anti-pattern 검증"
+  "evaluator_mode": "playwright-web",
+  "notes": "Flutter Web — 컴파일 결과가 HTML+JS+CSS 이므로 React 경로의 Playwright evaluator 사용. Generator 의 Self-Verification 에서 flutter analyze/test 통과 전제."
 }
 ```
 
-### fe_stack → 파이프라인 매핑
-
-| pipeline | fe_stack | agents_active 예시 |
-|----------|----------|-------------------|
-| FULLSTACK | react | planner, generator-backend, generator-frontend, evaluator-functional, evaluator-visual |
-| FULLSTACK | flutter | planner, generator-backend, generator-frontend-flutter, evaluator-functional-flutter |
-| FE-ONLY | react | planner, generator-frontend, evaluator-functional, evaluator-visual |
-| FE-ONLY | flutter | planner, generator-frontend-flutter, evaluator-functional-flutter |
-| BE-ONLY | (무관) | planner, generator-backend, evaluator-functional |
+### fe_stack + fe_target → 파이프라인 매핑
+
+| pipeline | fe_stack | fe_target | agents_active 예시 |
+|----------|----------|-----------|-------------------|
+| FULLSTACK | react | (n/a) | planner, generator-backend, generator-frontend, evaluator-functional, evaluator-visual |
+| FULLSTACK | flutter | **web** | planner, generator-backend, generator-frontend-flutter, evaluator-functional, evaluator-visual |
+| FULLSTACK | flutter | mobile | planner, generator-backend, generator-frontend-flutter, evaluator-functional-flutter |
+| FULLSTACK | flutter | desktop | planner, generator-backend, generator-frontend-flutter, evaluator-functional-flutter |
+| FE-ONLY | react | (n/a) | planner, generator-frontend, evaluator-functional, evaluator-visual |
+| FE-ONLY | flutter | **web** | planner, generator-frontend-flutter, evaluator-functional, evaluator-visual |
+| FE-ONLY | flutter | mobile | planner, generator-frontend-flutter, evaluator-functional-flutter |
+| BE-ONLY | (무관) | (n/a) | planner, generator-backend, evaluator-functional |
 
 ## 4. Flutter 선택 시 추가 작업