@wooojin/forgen 0.4.8 → 0.4.9

package/assets/dev-guide/fe/sources/vue/style-guide-priority-a.md

@@ -0,0 +1,117 @@
+---
+title: Vue 3 스타일 가이드 - Priority A (Essential)
+source: https://vuejs.org/style-guide/rules-essential
+fetched: 2026-05-18
+category: style-guide
+vue_version: 3
+---
+
+# Priority A: Essential
+
+반드시 지켜야 하는 규칙. 위반 시 버그 또는 예측 불가 동작이 발생한다.
+
+---
+
+## 1. 멀티-워드 컴포넌트 이름
+
+**규칙:** 루트 `App` 컴포넌트를 제외한 모든 사용자 정의 컴포넌트는 반드시 다단어 이름을 사용한다. HTML 요소는 모두 단일 단어이므로 충돌을 방지한다.
+
+```vue
+<!-- Bad -->
+<Item />
+<!-- Good -->
+<TodoItem />
+```
+
+---
+
+## 2. 상세한 Prop 정의
+
+**규칙:** 커밋된 코드에서 prop 정의는 가능한 한 상세하게 작성하고, 최소한 타입은 지정해야 한다.
+
+```js
+// Bad
+const props = defineProps(['status'])
+
+// Good
+const props = defineProps({
+  status: String
+})
+
+// Best
+const props = defineProps({
+  status: {
+    type: String,
+    required: true,
+    validator: (value) => {
+      return ['syncing', 'synced', 'version-conflict', 'error'].includes(value)
+    }
+  }
+})
+```
+
+---
+
+## 3. v-for에 key 사용
+
+**규칙:** 컴포넌트의 `v-for`에는 반드시 `key`를 사용한다.
+
+```vue
+<!-- Bad -->
+<li v-for="todo in todos">{{ todo.text }}</li>
+
+<!-- Good -->
+<li v-for="todo in todos" :key="todo.id">{{ todo.text }}</li>
+```
+
+---
+
+## 4. v-if와 v-for 혼용 금지
+
+**규칙:** 같은 요소에 `v-if`와 `v-for`를 함께 사용하지 않는다. Vue에서 `v-if`가 `v-for`보다 우선순위가 높아 반복 변수에 접근이 불가하다.
+
+```vue
+<!-- Bad -->
+<li v-for="user in users" v-if="user.isActive" :key="user.id">
+
+<!-- Good: computed로 필터링 -->
+<li v-for="user in activeUsers" :key="user.id">
+
+<!-- Good: template 래퍼 사용 -->
+<template v-for="user in users" :key="user.id">
+  <li v-if="user.isActive">{{ user.name }}</li>
+</template>
+```
+
+```js
+// Composition API
+const activeUsers = computed(() => users.filter((user) => user.isActive))
+```
+
+---
+
+## 5. 컴포넌트 스코프 스타일링
+
+**규칙:** 앱 레벨 및 레이아웃 컴포넌트를 제외한 모든 컴포넌트의 스타일은 반드시 스코프를 가져야 한다.
+
+```vue
+<!-- Bad: 전역 스타일 -->
+<style>
+.btn-close { background-color: red; }
+</style>
+
+<!-- Good: scoped -->
+<style scoped>
+.btn-close { background-color: red; }
+</style>
+
+<!-- Good: CSS Modules -->
+<style module>
+.btnClose { background-color: red; }
+</style>
+
+<!-- Good: BEM -->
+<style>
+.c-Button--close { background-color: red; }
+</style>
+```

package/assets/dev-guide/fe/sources/vue/style-guide-priority-b.md

@@ -0,0 +1,231 @@
+---
+title: Vue 3 스타일 가이드 - Priority B (Strongly Recommended)
+source: https://vuejs.org/style-guide/rules-strongly-recommended
+fetched: 2026-05-18
+category: style-guide
+vue_version: 3
+---
+
+# Priority B: Strongly Recommended
+
+코드 가독성과 DX를 향상시킨다. 위반 시 코드는 동작하나 정당한 이유가 있어야 한다.
+
+---
+
+## 1. 컴포넌트 파일 분리
+
+각 컴포넌트는 별도 파일로 분리한다.
+
+```
+components/
+|- TodoList.vue
+|- TodoItem.vue
+```
+
+---
+
+## 2. SFC 파일명 케이싱
+
+PascalCase 또는 kebab-case 중 하나를 일관되게 사용한다.
+
+```
+# Good (PascalCase)
+components/|- MyComponent.vue
+
+# Good (kebab-case)
+components/|- my-component.vue
+```
+
+---
+
+## 3. 베이스 컴포넌트 이름 접두사
+
+순수 프레젠테이션 컴포넌트는 `Base`, `App`, `V` 접두사를 붙인다.
+
+```
+# Bad
+|- MyButton.vue, Icon.vue
+
+# Good
+|- BaseButton.vue, BaseTable.vue, BaseIcon.vue
+```
+
+Vite 자동 전역 등록:
+```js
+const modules = import.meta.glob('./src/**/Base*.vue', { eager: true })
+for (const path in modules) {
+  const config = modules[path].default
+  const name = config.name || path.match(/Base[A-Z]\w+/)[0]
+  app.component(name, config)
+}
+```
+
+---
+
+## 4. 강하게 결합된 컴포넌트 이름
+
+부모에 종속된 자식 컴포넌트는 부모 이름을 접두사로 사용한다.
+
+```
+# Bad
+|- TodoList.vue, TodoItem.vue, TodoButton.vue
+
+# Good (연관성 명확)
+|- TodoList.vue, TodoListItem.vue, TodoListItemButton.vue
+```
+
+---
+
+## 5. 컴포넌트 이름 단어 순서
+
+가장 일반적인 단어부터 시작하고, 수식어를 뒤에 붙인다.
+
+```
+# Bad
+|- ClearSearchButton.vue, RunSearchButton.vue
+
+# Good
+|- SearchButtonClear.vue, SearchButtonRun.vue, SearchInputQuery.vue
+```
+
+---
+
+## 6. 셀프 클로징 컴포넌트
+
+SFC/JSX에서 콘텐츠 없는 컴포넌트는 셀프 클로징한다. in-DOM 템플릿에서는 사용하지 않는다.
+
+```vue
+<!-- Good: SFC/JSX -->
+<MyComponent/>
+
+<!-- Good: in-DOM template -->
+<my-component></my-component>
+```
+
+---
+
+## 7. 템플릿에서 컴포넌트 이름 케이싱
+
+SFC: PascalCase / in-DOM: kebab-case
+
+```vue
+<MyComponent/>          <!-- SFC -->
+<my-component></my-component>  <!-- in-DOM -->
+```
+
+---
+
+## 8. JS/JSX에서 PascalCase
+
+```js
+import MyComponent from './MyComponent.vue'
+export default { name: 'MyComponent' }
+```
+
+---
+
+## 9. Prop 이름 케이싱
+
+선언: camelCase / in-DOM 템플릿: kebab-case
+
+```js
+// 선언
+const props = defineProps({ greetingText: String })
+```
+
+```vue
+<!-- SFC -->
+<WelcomeMessage greeting-text="hi"/>
+<!-- in-DOM -->
+<welcome-message greeting-text="hi"></welcome-message>
+```
+
+---
+
+## 10. 멀티 속성 요소 줄 분리
+
+여러 속성은 한 줄에 하나씩 작성한다.
+
+```vue
+<!-- Bad -->
+<MyComponent foo="a" bar="b" baz="c"/>
+
+<!-- Good -->
+<MyComponent
+  foo="a"
+  bar="b"
+  baz="c"
+/>
+```
+
+---
+
+## 11. 템플릿에서 단순 표현식
+
+복잡한 로직은 computed나 method로 분리한다.
+
+```vue
+<!-- Bad -->
+{{ fullName.split(' ').map((word) => word[0].toUpperCase() + word.slice(1)).join(' ') }}
+
+<!-- Good -->
+{{ normalizedFullName }}
+```
+
+```js
+const normalizedFullName = computed(() =>
+  fullName.value
+    .split(' ')
+    .map((word) => word[0].toUpperCase() + word.slice(1))
+    .join(' ')
+)
+```
+
+---
+
+## 12. 단순 computed 속성
+
+복잡한 computed는 여러 단순한 속성으로 분리한다.
+
+```js
+// Bad
+const price = computed(() => {
+  const basePrice = manufactureCost.value / (1 - profitMargin.value)
+  return basePrice - basePrice * (discountPercent.value || 0)
+})
+
+// Good
+const basePrice = computed(() => manufactureCost.value / (1 - profitMargin.value))
+const discount = computed(() => basePrice.value * (discountPercent.value || 0))
+const finalPrice = computed(() => basePrice.value - discount.value)
+```
+
+---
+
+## 13. 속성 값 인용
+
+비어있지 않은 HTML 속성 값은 항상 따옴표로 감싼다.
+
+```vue
+<!-- Bad -->
+<input type=text>
+
+<!-- Good -->
+<input type="text">
+```
+
+---
+
+## 14. 디렉티브 단축형 일관성
+
+`:`, `@`, `#` 단축형을 항상 사용하거나, 항상 사용하지 않는다. 혼용 금지.
+
+```vue
+<!-- Good: 항상 단축형 -->
+<input :value="val" @input="onInput">
+<template #header>...</template>
+
+<!-- Good: 항상 전체형 -->
+<input v-bind:value="val" v-on:input="onInput">
+<template v-slot:header>...</template>
+```

package/assets/dev-guide/fe/sources/vue/style-guide-priority-c.md

@@ -0,0 +1,86 @@
+---
+title: Vue 3 스타일 가이드 - Priority C (Recommended)
+source: https://vuejs.org/style-guide/rules-recommended
+fetched: 2026-05-18
+category: style-guide
+vue_version: 3
+---
+
+# Priority C: Recommended
+
+여러 동등한 선택지가 있을 때 일관성을 위해 권장되는 규칙.
+
+---
+
+## 1. 컴포넌트/인스턴스 옵션 순서 (Options API)
+
+1. `name`
+2. `compilerOptions`
+3. `components`, `directives`
+4. `extends`, `mixins`, `provide`/`inject`
+5. `inheritAttrs`, `props`, `emits`, `expose`
+6. `setup`
+7. `data`, `computed`
+8. `watch`, lifecycle hooks (`beforeCreate` → `serverPrefetch` 순서)
+9. `methods`
+10. `template`/`render`
+
+---
+
+## 2. 요소 속성 순서
+
+1. `is`
+2. `v-for`
+3. `v-if`, `v-else-if`, `v-else`, `v-show`, `v-cloak`
+4. `v-pre`, `v-once`
+5. `id`
+6. `ref`, `key`
+7. `v-model`
+8. 기타 바인딩/속성
+9. `v-on`
+10. `v-html`, `v-text`
+
+---
+
+## 3. 컴포넌트/인스턴스 옵션 사이 빈 줄
+
+여러 줄 속성 사이에는 빈 줄을 추가해 가독성을 높인다.
+
+```js
+// Good (Composition API)
+defineProps({
+  value: {
+    type: String,
+    required: true
+  },
+
+  focused: {
+    type: Boolean,
+    default: false
+  },
+
+  label: String,
+})
+
+const formattedValue = computed(() => { /* ... */ })
+
+const inputClasses = computed(() => { /* ... */ })
+```
+
+---
+
+## 4. SFC 최상위 요소 순서
+
+`<script>`, `<template>`, `<style>` 순서를 프로젝트 전체에서 일관되게 유지한다. `<style>`은 항상 마지막.
+
+```vue
+<!-- Option 1: script first -->
+<script>/* ... */</script>
+<template>...</template>
+<style>/* ... */</style>
+
+<!-- Option 2: template first -->
+<template>...</template>
+<script>/* ... */</script>
+<style>/* ... */</style>
+```

package/assets/dev-guide/fe/sources/vue/style-guide-priority-d.md

@@ -0,0 +1,72 @@
+---
+title: Vue 3 스타일 가이드 - Priority D (Use with Caution)
+source: https://vuejs.org/style-guide/rules-use-with-caution
+fetched: 2026-05-18
+category: style-guide
+vue_version: 3
+---
+
+# Priority D: Use with Caution
+
+드문 엣지 케이스나 레거시 마이그레이션을 위해 존재하며, 과용 시 유지보수가 어려워진다.
+
+---
+
+## 1. scoped에서 요소 선택자 지양
+
+`scoped`에서 요소 선택자는 class 선택자보다 훨씬 느리다. 반드시 class를 사용한다.
+
+```vue
+<!-- Bad: 요소 선택자 (느림) -->
+<style scoped>
+button { background-color: red; }
+</style>
+
+<!-- Good: class 선택자 (빠름) -->
+<template>
+  <button class="btn btn-close">×</button>
+</template>
+<style scoped>
+.btn-close { background-color: red; }
+</style>
+```
+
+**이유:** Vue는 `scoped` 사용 시 `button[data-v-f3f3eg9]` 형태로 변환하는데, 이 속성-요소 복합 선택자는 `.btn-close[data-v-f3f3eg9]`보다 현저히 느리다.
+
+---
+
+## 2. 암묵적 부모-자식 통신 지양
+
+`this.$parent`나 prop 직접 변경 대신 props down / events up 패턴을 따른다.
+
+```vue
+<!-- Bad: prop 직접 변경 -->
+<script setup>
+const props = defineProps({ todo: { type: Object, required: true } })
+
+function renameTodo() {
+  props.todo.text = 'renamed by child'  // ❌ 부모 상태 직접 변경
+}
+</script>
+
+<!-- Good: emit으로 업데이트 요청 -->
+<script setup>
+const props = defineProps({ todo: { type: Object, required: true } })
+const emit = defineEmits(['update:todo'])
+
+function renameTodo() {
+  emit('update:todo', { ...props.todo, text: 'renamed by parent' })  // ✅
+}
+</script>
+```
+
+```vue
+<!-- Bad: this.$parent 사용 -->
+<!-- Good: emit('delete') 사용 -->
+<script setup>
+const emit = defineEmits(['delete'])
+</script>
+<template>
+  <button @click="emit('delete')">×</button>
+</template>
+```

package/dist/cli.js

@@ -186,6 +186,48 @@ const commands = [
             console.log(renderResult(result, dryRun));
         },
     },
+    {
+        name: 'status',
+        description: 'Observability dashboard (--watch, --json, --interval N)',
+        handler: async (args) => {
+            const { runDashboard } = await import('./core/dashboard-cli.js');
+            const watch = args.includes('--watch');
+            const json = args.includes('--json');
+            const intervalIdx = args.indexOf('--interval');
+            const intervalSec = intervalIdx !== -1 ? Number(args[intervalIdx + 1]) || 5 : 5;
+            await runDashboard({ watch, json, intervalSec });
+        },
+    },
+    {
+        name: 'maintenance',
+        description: 'Maintenance utilities (--backfill [--phase A|B|all] [--force] [--dry-run])',
+        handler: async (args) => {
+            if (args.includes('--backfill')) {
+                const phaseArg = args[args.indexOf('--phase') + 1];
+                const phase = (phaseArg === 'A' || phaseArg === 'B' || phaseArg === 'all') ? phaseArg : 'A';
+                const force = args.includes('--force');
+                const dryRun = args.includes('--dry-run');
+                const { runBackfill } = await import('./core/observability-backfill.js');
+                try {
+                    const result = await runBackfill({ phase, force, dryRun });
+                    const dryTag = dryRun ? ' [dry-run]' : '';
+                    console.log(`\n  [forgen] Backfill complete${dryTag}:`);
+                    console.log(`    Phase A — matched: ${result.phaseA.matched}, surfaced: ${result.phaseA.surfaced}, acted_on: ${result.phaseA.acted_on}`);
+                    if (phase !== 'A')
+                        console.log(`    Phase B — acted_on: ${result.phaseB.acted_on}`);
+                    console.log(`    Total: ${result.total} events, ${result.durationMs}ms\n`);
+                }
+                catch (e) {
+                    console.error(`  [forgen] Backfill 실패: ${e instanceof Error ? e.message : String(e)}`);
+                    console.error('  --force 플래그로 강행하거나 --dry-run 으로 미리 확인하세요.');
+                    process.exit(1);
+                }
+            }
+            else {
+                console.log('Usage:\n  forgen maintenance --backfill [--phase A|B|all] [--force] [--dry-run]');
+            }
+        },
+    },
     {
         name: 'parity',
         description: 'Run host parity checks. Usage: forgen parity codex [--dry-run]',

package/dist/core/dashboard-cli.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Forgen — Dashboard CLI (P3)
+ *
+ * `fgx status [--watch] [--json] [--interval N]`
+ * ANSI box-drawing 기반 상태 대시보드. TUI 라이브러리 없음.
+ */
+export interface DashboardOptions {
+    watch?: boolean;
+    json?: boolean;
+    intervalSec?: number;
+}
+export declare function runDashboard(opts: DashboardOptions): Promise<void>;