create-harness-cli 0.1.0

package/templates/core/workflows/ds-init.md

@@ -0,0 +1,59 @@
+---
+description: One-time on-demand Storybook setup with a11y-as-error and vitest integration.
+---
+
+# /ds-init — Storybook 온디맨드 설치 (최초 1회)
+
+UI 작업이 처음 필요해진 시점에 실행한다. 이미 `.storybook/` 이 있으면 실행하지 않는다.
+
+## 절차
+
+1. **공식 CLI로 설치** (손으로 설정 파일을 쓰지 않는다 — 프레임워크·빌더 감지는 CLI가 한다):
+
+```bash
+{{PM_EXEC}} storybook@latest init --no-dev --yes
+```
+
+   Vite 프로젝트면 최신 Storybook init이 `addon-vitest`·`addon-a11y`까지 함께 설치한다.
+   설치 후 `package.json` 에 없으면 그때만 수동 추가:
+
+```bash
+{{PM_EXEC}} storybook add @storybook/addon-vitest
+{{PM_EXEC}} storybook add @storybook/addon-a11y
+```
+
+2. **접근성 위반을 검증 실패로**: `.storybook/preview.(ts|tsx)` 의 `parameters.a11y.test` 를
+   `'todo'`(init 기본값)에서 `'error'` 로 바꾼다:
+
+```ts
+a11y: {
+    test: 'error',
+},
+```
+
+3. **린트 정합**: Storybook이 만든 파일이 프로젝트 eslint에 걸리지 않게 한다.
+   - 타입 인식 린트(parserOptions.project)를 쓰는 프로젝트면 eslint ignores에
+     `.storybook/**` 와 `vitest.shims.d.ts`(addon-vitest 생성물) 추가
+   - 스토리 export(PascalCase)가 naming-convention에 걸리면 `**/*.stories.{ts,tsx}` 오버라이드로
+     해당 규칙을 끈다 (하네스 lint 모듈의 `eslint.harness.config.js` 에는 이미 포함)
+   - init이 만든 예제(`src/stories/`)는 프로젝트 컨벤션에 안 맞으면 삭제한다
+
+4. **checks에 등록**: `.harness/config.json` 의 `checks` 배열에서 `test` 항목 **앞**에 추가
+   (addon-vitest 설치가 vitest workspace를 구성해준 경우):
+
+```json
+{ "id": "test-storybook", "command": "{{PM_EXEC}} vitest --project=storybook --run" }
+```
+
+5. **참조 구현 생성**: `src/design-system/examples/` 아래에 이 프로젝트의 토큰과 컴포넌트만 쓰는
+   예제 3종을 만든다 — 폼(`ExampleForm`), 데이터 테이블(`ExampleTable`), 상세 페이지(`ExampleDetail`).
+   각각 스토리 포함. 이 예제들은 컴파일되는 코드이므로 API가 바뀌면 깨진다 —
+   그게 목적이다. 에이전트(자신 포함)가 산문 문서 대신 이 코드를 모방하게 된다.
+6. **확인**: `{{PM_RUN}} storybook` 으로 기동 확인 후,
+   `node .harness/gates/run-checks.mjs` 전체 통과 확인.
+
+## 완료 조건
+
+- `.storybook/` 존재, a11y test = 'error'
+- checks에 storybook 테스트 등록
+- `src/design-system/examples/` 3종 + 스토리

package/templates/core/workflows/impl.md

@@ -0,0 +1,26 @@
+---
+description: Implement from a spec, failing tests first (Red-Green-Refactor).
+---
+
+# /impl — 명세 기반 구현 (테스트 우선)
+
+`docs/specs/<slug>.md` 를 읽고 구현한다. 명세가 없으면 먼저 `/spec` 을 요청한다.
+
+## 절차
+
+1. **명세 읽기**: 수용 기준 목록을 확인한다. 모호하면 구현 전에 질문한다.
+2. **UI 작업인지 판단**: 새 화면·컴포넌트가 필요하면 먼저 디자인시스템 절차를 따른다:
+   - 필요한 컴포넌트가 `src/design-system/components/` 에 없으면 `/ds-add` 선행
+   - Storybook 미설치 상태면 `/ds-init` 선행
+3. **Red**: 수용 기준 하나당 실패하는 테스트를 먼저 쓴다. 실행해서 **실패를 확인**한다.
+   (실패를 확인하지 않은 테스트는 아무것도 검증하지 않는 테스트일 수 있다)
+4. **Green**: 테스트를 통과시키는 최소 구현을 쓴다. 이 단계에서 리팩터링·범위 확장 금지.
+5. **Refactor**: 테스트가 초록인 상태에서 정리한다. 중복 제거, 이름 개선, 레이어 위치 조정.
+6. 수용 기준을 모두 소화할 때까지 3–5를 반복한다.
+7. `node .harness/gates/run-checks.mjs` 로 전체 검증을 돌린다.
+
+## 금지
+
+- 테스트 없이 구현부터 쓰기
+- 실패하는 테스트를 통과시키려고 단정문 약화 (`40-testing` 규칙)
+- 명세에 없는 기능 끼워넣기 — 필요해 보이면 명세에 추가 제안부터

package/templates/core/workflows/ship.md

@@ -0,0 +1,31 @@
+---
+description: Verify, review test integrity, commit with conventional message, log to task-log.
+---
+
+# /ship — 검증하고 커밋
+
+작업을 마무리해 커밋한다. 게이트가 있지만, 게이트에 걸리기 전에 스스로 검증한다.
+
+## 절차
+
+1. **검증**: `node .harness/gates/run-checks.mjs` 전체 통과 확인. 실패하면 `/verify` 루프.
+2. **테스트 무결성 검토**: 이번 변경에서 수정된 테스트 파일을 diff로 확인한다.
+   - 단정문이 약해진 곳(`toBe` → `toBeTruthy`, 삭제된 expect, 추가된 skip)이 있으면
+     커밋을 멈추고 사용자에게 보고한다.
+3. **스테이징 검토**: `git status` 와 `git diff --cached` 로 의도한 파일만 올라갔는지 확인.
+   - `.env*`, 디버깅 로그, 무관한 파일이 섞여 있으면 뺀다.
+4. **커밋**: Conventional Commits 형식으로. 본문에는 "왜"를 적는다.
+
+```bash
+git add <의도한 파일들>
+git commit -m "feat: <무엇> — <왜>"
+```
+
+5. **기록**: `docs/task-log.md` 맨 위에 한 줄 추가:
+   `- YYYY-MM-DD <커밋 해시 앞 7자> <요약>`
+6. push는 사용자가 요청했을 때만 한다. `--force` 금지.
+
+## 금지
+
+- `git commit --no-verify` — 게이트 우회 금지
+- 검증 실패 상태에서 "일단 커밋" — 없다

package/templates/core/workflows/spec.md

@@ -0,0 +1,26 @@
+---
+description: Write a spec before implementation. Acceptance criteria must map 1:1 to tests.
+---
+
+# /spec — 구현 전 명세 작성
+
+기능 설명을 받아 `docs/specs/<slug>.md` 를 작성한다. 코드는 건드리지 않는다.
+
+## 절차
+
+1. `docs/specs/_template.md` 를 복사해 `<slug>.md` 를 만든다 (slug는 kebab-case).
+2. 사용자와의 대화·기존 코드에서 다음을 채운다:
+   - **목표**: 이 기능이 해결하는 문제 한 문단
+   - **범위 밖**: 이번에 하지 않는 것 (스코프 크리프 방지에 가장 중요)
+   - **수용 기준**: 각 항목이 **테스트 하나로 번역 가능한 문장**이어야 한다.
+     "잘 동작한다" 같은 검증 불가능한 문장 금지.
+     예: "빈 목록이면 '데이터 없음' 문구가 보인다" (O) / "UX가 좋다" (X)
+3. 영향 범위를 조사해 적는다: 만질 파일, 새 의존성, 기존 기능에의 영향.
+4. 모호한 부분이 있으면 **추측하지 말고 사용자에게 질문**한다.
+5. 완성된 명세를 사용자에게 보여주고 확인을 받는다. 확인 전에 `/impl` 로 넘어가지 않는다.
+
+## 완료 조건
+
+- `docs/specs/<slug>.md` 존재
+- 수용 기준 각각이 테스트로 번역 가능
+- 사용자 확인 완료

package/templates/core/workflows/verify.md

@@ -0,0 +1,27 @@
+---
+description: Run all checks from .harness/config.json sequentially and fix failures in a loop.
+---
+
+# /verify — 전체 검증 실행
+
+`.harness/config.json` 의 `checks` 를 순서대로 전부 실행하고, 실패를 고친다.
+
+## 절차
+
+1. 실행:
+
+```bash
+node .harness/gates/run-checks.mjs
+```
+
+2. 실패한 체크가 있으면:
+   - 출력을 읽고 **원인을 고친다** (에러를 숨기거나 체크를 비활성화하지 않는다)
+   - 다시 1부터. 모든 체크가 통과할 때까지 반복한다.
+3. 반복해도 못 고치는 실패는 상황을 정리해 사용자에게 보고한다:
+   - 어떤 체크가, 어떤 에러로, 무엇을 시도했는지
+
+## 금지
+
+- 체크를 통과시키기 위한 `eslint-disable`·`@ts-ignore`·`it.skip` 남발.
+  정말 필요하면 이유 주석과 함께 최소 범위로만.
+- `.harness/config.json` 에서 실패하는 체크를 삭제하는 것 — 체크 목록 변경은 사용자 승인 사항이다.

package/templates/presets/react-fe/configs/commitlint.config.js

@@ -0,0 +1,36 @@
+/**
+ * Conventional Commits 검증 — /ship 워크플로와 게이트가 전제하는 커밋 형식.
+ * https://www.conventionalcommits.org/
+ */
+export default {
+    extends: ['@commitlint/config-conventional'],
+    rules: {
+        'type-enum': [
+            2,
+            'always',
+            [
+                'feat', // 새 기능 (MINOR)
+                'fix', // 버그 수정 (PATCH)
+                'docs', // 문서
+                'style', // 포맷팅 (동작 변화 없음)
+                'refactor', // 리팩토링
+                'perf', // 성능
+                'test', // 테스트
+                'chore', // 빌드·설정
+                'ci', // CI
+                'build', // 빌드 시스템
+                'revert', // 되돌리기
+            ],
+        ],
+        'type-case': [2, 'always', 'lower-case'],
+        'subject-case': [0],
+        'subject-empty': [2, 'never'],
+        'type-empty': [2, 'never'],
+    },
+    ignorePatterns: [
+        '^Merge branch',
+        '^Merge pull request',
+        '^Merge remote-tracking branch',
+        '^Revert "',
+    ],
+}

package/templates/presets/react-fe/configs/eslint.harness.config.js

@@ -0,0 +1,104 @@
+/**
+ * 하네스 린트 규칙 조각 — 기존 eslint.config.js 에 spread해서 쓴다:
+ *
+ *   import harnessRules from './eslint.harness.config.js'
+ *   export default [ ...기존설정, ...harnessRules ]
+ *
+ * 문서만 있으면 에이전트가 무시한다. 컨벤션은 여기서 error로 강제된다.
+ * 필요 devDependency: typescript-eslint, eslint-plugin-import
+ */
+import importPlugin from 'eslint-plugin-import'
+import tseslint from 'typescript-eslint'
+
+export default [
+    {
+        files: ['src/**/*.{ts,tsx}'],
+        plugins: {
+            '@typescript-eslint': tseslint.plugin,
+            import: importPlugin,
+        },
+        rules: {
+            // ── 명명 규칙 (10-architecture) ─────────────────────────────
+            '@typescript-eslint/naming-convention': [
+                'error',
+                {
+                    selector: 'variable',
+                    types: ['boolean'],
+                    format: ['PascalCase', 'camelCase'],
+                    prefix: ['is', 'has', 'should', 'can', 'must', 'was', 'will'],
+                },
+                {
+                    selector: 'variable',
+                    format: ['camelCase'],
+                    leadingUnderscore: 'allow',
+                },
+                {
+                    selector: 'variable',
+                    modifiers: ['const'],
+                    format: ['UPPER_CASE', 'camelCase'],
+                    filter: { regex: '^[_A-Z0-9]+$', match: true },
+                },
+                { selector: 'function', format: ['PascalCase', 'camelCase'] },
+                { selector: 'class', format: ['PascalCase'] },
+                {
+                    selector: 'interface',
+                    format: ['PascalCase'],
+                    custom: { regex: '^I[A-Z]', match: true },
+                },
+                { selector: 'typeAlias', format: ['PascalCase'] },
+                {
+                    selector: 'typeParameter',
+                    format: ['PascalCase'],
+                    prefix: ['T'],
+                },
+            ],
+
+            // ── any 금지 (00-core) ──────────────────────────────────────
+            '@typescript-eslint/no-explicit-any': 'error',
+
+            // ── 공개 API 경계 (10-architecture) ─────────────────────────
+            // 기능 폴더는 index.ts 로만 import. 내부 파일 deep import를 차단한다.
+            // (폴더 내부의 상대 import './exampleApi' 는 패턴에 안 걸린다)
+            'no-restricted-imports': [
+                'error',
+                {
+                    patterns: [
+                        {
+                            group: [
+                                '**/queries/*/*',
+                                '!**/queries/*/index',
+                                '**/components/*/*/*',
+                            ],
+                            message:
+                                '기능 폴더는 index.ts 공개 API로만 import하세요 (10-architecture).',
+                        },
+                    ],
+                },
+            ],
+
+            // ── import 정렬 ─────────────────────────────────────────────
+            'import/order': [
+                'error',
+                {
+                    groups: [
+                        ['builtin', 'external'],
+                        ['internal', 'parent', 'sibling', 'index'],
+                    ],
+                    'newlines-between': 'always',
+                    alphabetize: { order: 'asc', caseInsensitive: true },
+                },
+            ],
+        },
+    },
+    {
+        // 스토리 export(Default, Interaction 등)는 관례상 PascalCase — 명명 규칙 예외
+        files: ['src/**/*.stories.{ts,tsx}'],
+        rules: {
+            '@typescript-eslint/naming-convention': 'off',
+        },
+    },
+    {
+        // 하네스 인프라(.harness/)와 incoming 은 린트 대상이 아니다
+        ignores: ['.harness/**'],
+    },
+]

package/templates/presets/react-fe/configs/prettier.config.js

@@ -0,0 +1,9 @@
+export default {
+    semi: false,
+    singleQuote: true,
+    trailingComma: 'all',
+    printWidth: 80,
+    tabWidth: 4,
+    bracketSpacing: true,
+    endOfLine: 'auto',
+}

package/templates/presets/react-fe/design-system/_story-template.tsx

@@ -0,0 +1,56 @@
+/* eslint-disable */
+// ↑ 이 파일은 렌더되지 않는 참고용 템플릿이라 린트 대상에서 제외한다. 복사 후 제거하세요.
+/**
+ * 스토리 작성 템플릿 — 새 디자인시스템 컴포넌트의 스토리는 이 형식을 따른다.
+ * (규칙: 30-design-system, 40-testing)
+ *
+ * 이 파일 자체는 렌더되지 않는 참고용이다 (일부러 *.stories.tsx 이름을 피했다 —
+ * Storybook 러너가 집어들면 안 되기 때문). 실제 스토리를 만들 때:
+ *  1. 이 파일을 복사해 components/<Name>/<Name>.stories.tsx 로
+ *  2. 아래 TODO들을 채우고, play 함수에 상호작용·포커스·aria 단정을 쓴다
+ *
+ * play 함수가 스크린샷으로 못 잡는 것(포커스 이동, 키보드 조작, aria 상태)을 잡는다.
+ * 테스트를 통과시키려고 단정문을 약화시키지 않는다.
+ */
+// @ts-nocheck — 템플릿 파일. 복사 후 @ts-nocheck 을 제거하세요.
+import type { Meta, StoryObj } from '@storybook/react'
+import { expect } from 'storybook/test'
+
+// TODO: import MyComponent from './MyComponent'
+declare const MyComponent: (props: { label: string }) => JSX.Element
+
+const meta = {
+    title: 'DesignSystem/MyComponent', // TODO: 카테고리/이름
+    component: MyComponent,
+    tags: ['autodocs'],
+    parameters: {
+        // a11y 위반은 테스트 실패다 (.storybook/preview 에서 전역 설정됨)
+    },
+} satisfies Meta<typeof MyComponent>
+
+export default meta
+type TStory = StoryObj<typeof meta>
+
+export const Default: TStory = {
+    args: {
+        label: '기본',
+    },
+}
+
+export const Interaction: TStory = {
+    args: {
+        label: '저장',
+    },
+    play: async ({ canvas, userEvent }) => {
+        // 사용자 관점 쿼리(getByRole)를 우선한다
+        const button = canvas.getByRole('button', { name: '저장' })
+
+        // 키보드 접근성: Tab으로 도달 가능한가
+        await userEvent.tab()
+        await expect(button).toHaveFocus()
+
+        // 상호작용 후 상태 단정
+        await userEvent.click(button)
+        // TODO: await expect(canvas.getByRole('status')).toHaveTextContent('저장됨')
+    },
+}

package/templates/presets/react-fe/design-system/stylelint.config.js

@@ -0,0 +1,78 @@
+/**
+ * 디자인 토큰 강제 — 색상 원시값(#hex, rgb(), 색상 키워드)을 error 처리한다.
+ * 에이전트가 규칙 문서를 무시해도 여기서 걸린다.
+ *
+ * 색상만 켠다. 간격·타이포까지 한 번에 강제하면 토큰이 불완전한 상태에서
+ * 에이전트가 존재하지 않는 토큰 이름을 발명한다 — hex보다 나쁜 결과.
+ * src/design-system/tokens.css 의 해당 카테고리가 채워지면 아래 주석을 해제할 것.
+ */
+{{#if STYLELINT_BASELINE}}import { readFileSync } from 'node:fs'
+
+/**
+ * 유예 목록 — 하네스 도입 시점에 이미 원시값을 쓰던 CSS {{CSS_RAW_COLOR_FILES}}개.
+ * 이 파일들만 warning 으로 낮춘다. **새로 만드는 CSS는 그대로 error다.**
+ *
+ * 전부 error로 켜면 첫 커밋부터 막혀 게이트를 꺼버리게 되고, 반대로 전부 warning으로
+ * 낮추면 새 코드의 드리프트를 못 막는다. 목록으로 끊는 이유가 그것이다.
+ *
+ * 정리할 때마다 .harness/stylelint-baseline.json 에서 해당 경로를 지운다.
+ * 목록이 비면 이 블록과 overrides 를 통째로 삭제하면 된다.
+ */
+const baseline = JSON.parse(
+    readFileSync(new URL('./.harness/stylelint-baseline.json', import.meta.url), 'utf-8'),
+)
+
+{{/if}}const TOKEN_PROPERTIES = [
+    // 색상 — 항상 강제
+    '/color$/',
+    'fill',
+    'stroke',
+    'background',
+    'border-color',
+    'outline-color',
+
+    // 간격 — tokens.css 의 --space-* 가 실사용 값으로 채워지면 해제
+    // 'gap', 'padding', 'margin',
+
+    // 타이포 — --font-* 가 채워지면 해제
+    // 'font-size', 'font-weight',
+]
+
+const OPTIONS = {
+    ignoreValues: [
+        'currentColor',
+        'transparent',
+        'inherit',
+        'initial',
+        'unset',
+        'none',
+        '/^var\\(--/',
+    ],
+    message:
+        '원시값 대신 디자인 토큰(var(--...))을 쓰세요. 토큰이 없으면 src/design-system/tokens.css 에 먼저 추가하세요.',
+}
+
+/**
+ * strict-value 플러그인은 함수 값(ignoreFunctions 기본 true)을 건너뛴다.
+ * 그래서 `#hex` 는 잡아도 `rgb()` · `hsl()` 은 통과한다 — 색상 속성에 한해 따로 막는다.
+ * background-image 의 그라디언트는 대상이 아니므로 var() 조합은 그대로 쓸 수 있다.
+ */
+const COLOR_FUNCTION_PROPERTIES =
+    '/^(color|fill|stroke|background|background-color|border(-(top|right|bottom|left))?-color|outline-color)$/'
+
+const rules = (severity) => ({
+    'scale-unlimited/declaration-strict-value': [
+        TOKEN_PROPERTIES,
+        severity ? { ...OPTIONS, severity } : OPTIONS,
+    ],
+    'declaration-property-value-disallowed-list': [
+        { [COLOR_FUNCTION_PROPERTIES]: ['/rgba?\\(/', '/hsla?\\(/'] },
+        { message: OPTIONS.message, ...(severity ? { severity } : {}) },
+    ],
+})
+
+export default {
+    plugins: ['stylelint-declaration-strict-value'],
+    rules: rules(),
+{{#if STYLELINT_BASELINE}}    overrides: [{ files: baseline, rules: rules('warning') }],
+{{/if}}}

package/templates/presets/react-fe/design-system/tokens.css

@@ -0,0 +1,57 @@
+/**
+ * 디자인 토큰 정본 — 색상은 반드시 이 변수들만 사용한다 (stylelint가 원시값을 error 처리).
+ * 존재하지 않는 토큰 이름을 발명하지 말 것. 필요하면 여기와 tokens.ts 양쪽에 먼저 추가한다.
+ *
+ * TODO: 아래 중립 회색 기본값을 프로젝트 브랜드 값으로 교체하세요.
+ */
+:root {
+    /* ===== 색상 (stylelint 강제 대상) ===== */
+    /* 브랜드 */
+    --color-primary: #4f46e5; /* TODO: 브랜드 주 색상 */
+    --color-primary-hover: #4338ca;
+    --color-secondary: #64748b;
+
+    /* 표면·배경 */
+    --color-background: #ffffff;
+    --color-surface: #f8fafc;
+    --color-border: #e2e8f0;
+
+    /* 텍스트 */
+    --color-text: #0f172a;
+    --color-text-muted: #64748b;
+    --color-text-inverse: #ffffff;
+
+    /* 상태 */
+    --color-success: #16a34a;
+    --color-warning: #d97706;
+    --color-error: #dc2626;
+    --color-info: #0284c7;
+
+    /* ===== 간격 (v0.1은 강제 안 함 — 토큰이 채워지면 stylelint.config.js 에서 켤 것) ===== */
+    --space-1: 4px;
+    --space-2: 8px;
+    --space-3: 12px;
+    --space-4: 16px;
+    --space-6: 24px;
+    --space-8: 32px;
+
+    /* ===== radius ===== */
+    --radius-sm: 4px;
+    --radius-md: 8px;
+    --radius-lg: 16px;
+    --radius-full: 9999px;
+
+    /* ===== shadow ===== */
+    --shadow-sm: 0 1px 2px rgb(0 0 0 / 0.05);
+    --shadow-md: 0 4px 6px rgb(0 0 0 / 0.1);
+    --shadow-lg: 0 10px 15px rgb(0 0 0 / 0.1);
+
+    /* ===== 타이포 (v0.1은 강제 안 함) ===== */
+    --font-size-sm: 12px;
+    --font-size-base: 14px;
+    --font-size-lg: 16px;
+    --font-size-xl: 20px;
+    --font-weight-normal: 400;
+    --font-weight-medium: 500;
+    --font-weight-bold: 700;
+}

package/templates/presets/react-fe/design-system/tokens.ts

@@ -0,0 +1,40 @@
+/**
+ * tokens.css 의 타입드 미러 — TS/JSX에서 토큰 값이 필요할 때 이 상수를 import한다.
+ * (예: 차트 라이브러리 색상 배열, canvas 렌더링)
+ * 문자열 하드코딩 금지. tokens.css 에 변수를 추가하면 여기도 함께 추가한다.
+ */
+export const colorTokens = {
+    primary: 'var(--color-primary)',
+    primaryHover: 'var(--color-primary-hover)',
+    secondary: 'var(--color-secondary)',
+    background: 'var(--color-background)',
+    surface: 'var(--color-surface)',
+    border: 'var(--color-border)',
+    text: 'var(--color-text)',
+    textMuted: 'var(--color-text-muted)',
+    textInverse: 'var(--color-text-inverse)',
+    success: 'var(--color-success)',
+    warning: 'var(--color-warning)',
+    error: 'var(--color-error)',
+    info: 'var(--color-info)',
+} as const
+
+export const spaceTokens = {
+    1: 'var(--space-1)',
+    2: 'var(--space-2)',
+    3: 'var(--space-3)',
+    4: 'var(--space-4)',
+    6: 'var(--space-6)',
+    8: 'var(--space-8)',
+} as const
+
+export const radiusTokens = {
+    sm: 'var(--radius-sm)',
+    md: 'var(--radius-md)',
+    lg: 'var(--radius-lg)',
+    full: 'var(--radius-full)',
+} as const
+
+export type TColorToken = keyof typeof colorTokens
+export type TSpaceToken = keyof typeof spaceTokens
+export type TRadiusToken = keyof typeof radiusTokens

package/templates/presets/react-fe/reference/auth-http/ProtectedRoute.tsx

@@ -0,0 +1,62 @@
+/**
+ * 라우트 가드 — 로그인 필요 페이지는 이 컴포넌트로 감싼다.
+ * (규칙: 50-auth-http. 페이지 안에서 `if (!user) navigate(...)` 금지)
+ *
+ * 사용:
+ *   <ProtectedRoute><MyPage /></ProtectedRoute>
+ *   <ProtectedRoute requiredRoles={['ROLE_ADMIN']}><Admin /></ProtectedRoute>
+ *
+ * TODO: 아래 AuthContext 스텁을 프로젝트의 실제 인증 Provider와 연결하세요.
+ *       (인증 훅은 'auth:logout' 이벤트를 구독해 로그아웃·리다이렉트를 처리해야 합니다)
+ */
+import { createContext, useContext } from 'react'
+import { Navigate, useLocation } from 'react-router-dom'
+
+export type TRole = 'ROLE_USER' | 'ROLE_ADMIN'
+
+export interface IAuthState {
+    isAuthenticated: boolean
+    isLoading: boolean
+    role: TRole | null
+}
+
+// 프로젝트에 이미 AuthContext가 있다면 이 스텁을 지우고 그것을 import 하세요
+export const AuthContext = createContext<IAuthState>({
+    isAuthenticated: false,
+    isLoading: true,
+    role: null,
+})
+
+interface IProtectedRouteProps {
+    children: React.ReactNode
+    requiredAuth?: boolean
+    requiredRoles?: TRole[]
+}
+
+function ProtectedRoute({
+    children,
+    requiredAuth = true,
+    requiredRoles,
+}: IProtectedRouteProps) {
+    const { isAuthenticated, isLoading, role } = useContext(AuthContext)
+    const location = useLocation()
+
+    // 인증 여부 확인 중에는 아무것도 렌더하지 않는다 (깜빡임 방지)
+    if (isLoading) {
+        return null
+    }
+
+    if (!isAuthenticated && requiredAuth) {
+        return <Navigate to="/login" state={{ from: location }} replace />
+    }
+
+    if (requiredRoles && requiredRoles.length > 0) {
+        if (!role || !requiredRoles.includes(role)) {
+            return <Navigate to="/" replace />
+        }
+    }
+
+    return <>{children}</>
+}
+
+export default ProtectedRoute