@no-k/hermes 0.2.0 → 0.3.2

package/README.md

@@ -1,251 +1,217 @@
-# @no-k/hermes
+# Hermes
 
-Hermes CLI로 필요한 TypeScript 유틸 소스를 지정한 디렉터리에 생성합니다.
-선택한 유틸과 필요한 보조 파일은 npm 패키지에 함께 들어 있습니다.
-CLI는 터미널 화면에 Ink·React, 버전 범위 검사에 `semver`를 사용합니다.
+필요한 TypeScript 코드를 골라 프로젝트에 추가하세요.
 
-## 사용
+Hermes는 유틸리티, Tailwind CSS 헬퍼, FSD lint 규칙의 소스를 생성하는 CLI입니다.
+생성된 파일을 직접 읽고 수정하면서 프로젝트 코드와 함께 관리할 수 있습니다.
+선택한 항목에 필요한 보조 코드도 함께 가져옵니다.
 
-Node.js 22 이상이 필요합니다. 아래 명령은 공개 배포 후 사용할 수 있습니다.
+[시작하기](#시작하기) · [Tailwind CSS](#tailwind-css-헬퍼) · [FSD lint](#fsd-lint-규칙) · [명령어](#명령어)
+
+## 시작하기
+
+**Node.js 22 이상**이 필요합니다. 코드를 추가할 프로젝트 디렉터리의 터미널에서 실행하세요.
 
 ```bash
 npx @no-k/hermes@latest
-# 최신 카탈로그를 탐색하고 설치 계획만 확인
-npx @no-k/hermes@latest --dry-run
-# 특정 항목을 미리 체크한 상태로 시작
-npx @no-k/hermes@0.1.0 add array-chunk
 ```
 
-터미널에서 Core / 라이브러리 → 하위 분류 → 유틸을 여러 개 선택합니다.
-각 대분류의 경로와 기존 파일 처리를 검토한 뒤, 최종 목록에서 Yes를 선택하고 Enter를 누르면 설치합니다.
-No는 선택·경로·파일별 교체 결정을 유지하고 수정 화면으로 돌아갑니다.
-↑↓로 이동하고 Space로 체크합니다. `/`로 이름·한국어 설명을 검색한 뒤 Enter로 검색 입력을
-끝내고, Space로 항목을 체크합니다. 다시 Enter를 누르면 다음 단계로 이동합니다.
-Tab으로 설명·의존성을 자세히 보고 Esc로 돌아갈 수 있습니다.
-기본 경로로 array-chunk를 설치하면 다음 파일과 실행 디렉터리의 `no-k.config.ts`를 생성합니다.
+1. **코드 선택** — Core 또는 라이브러리에서 필요한 항목을 고릅니다.
+2. **경로 확인** — 파일을 생성할 위치와 기존 파일의 처리 방법을 확인합니다.
+3. **생성** — 최종 목록에서 `Yes`를 선택하고 Enter를 누릅니다.
+
+`No`를 선택하면 앞 화면으로 돌아가 선택 내용을 수정할 수 있습니다.
+
+| 키 | 동작 |
+| --- | --- |
+| ↑ / ↓ | 목록 이동 |
+| Space | 항목 선택·해제 |
+| Enter | 검색 입력 완료 또는 다음 단계 |
+| / | 이름이나 한국어 설명으로 검색 |
+| Tab | 항목 설명·의존성 또는 파일 차이 보기 |
+| Esc | 상세 보기 닫기 또는 이전 단계 |
+| Ctrl+C | 취소 |
+
+### 첫 번째 유틸 추가하기
+
+배열을 일정한 크기로 나누는 `array-chunk`를 추가해 보세요.
+
+```bash
+npx @no-k/hermes@latest add array-chunk
+```
+
+해당 항목이 선택된 상태로 시작합니다. 기본 경로를 사용하고 생성을 확인하면 다음 파일이 생깁니다.
 
 ```text
 src/utils/hermes/
-├── array/chunk/chunk.ts
-├── array/chunk/index.ts
+├── array/chunk/
+│   ├── chunk.ts
+│   └── index.ts
+├── index.ts
 └── LICENSE
+
+no-k.config.ts
 ```
 
-프로젝트의 실제 경로에 맞춰 import합니다.
+설치 루트의 `index.ts` 배럴에서 생성한 유틸을 바로 import해 사용하세요.
+이후 항목을 추가하면 기존 export와 주석을 보존하면서 필요한 export를 추가합니다.
 
 ```ts
-import { chunk } from "./utils/hermes/array/chunk";
+// src/example.ts
+import { chunk } from "./utils/hermes";
 
-chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+chunk([1, 2, 3, 4, 5], 2);
+// [[1, 2], [3, 4], [5]]
 ```
 
-`--dir`는 현재 작업 디렉터리 기준 상대 경로나 절대 경로를 받습니다.
-공백이 있는 경로는 따옴표로 감싸세요. 그 아래에는 유틸의 카테고리/이름 구조를 유지합니다.
-경로 입력의 초기값은 `--dir` → 현재 디렉터리의 저장된 설정 → 기본 경로 순서입니다.
-Core 기본값은 `src/utils/hermes`, 라이브러리는 `src/lib/hermes`이고 화면에서 각각 수정할 수 있습니다.
-경로 입력에서 Enter는 현재 값 사용, Ctrl+U는 전체 지우기, Esc는 이전 화면입니다.
-모노레포에서는 설치할 앱·패키지 디렉터리에서 실행합니다. 상위 디렉터리의 설정은 찾지 않습니다.
-설정 파일이나 package.json이 없는 디렉터리에서도 파일 생성이 가능합니다.
-설치가 성공하면 `no-k.config.ts`에 목적지, 선택한 유틸과 함께 복사한 모듈의 버전·해시를 저장합니다.
-기존 설정이 있으면 읽어서 갱신하며, `--dry-run`에서는 설정도 쓰지 않습니다.
+`no-k.config.ts`는 설치 위치와 항목의 버전을 기억합니다.
+생성된 소스와 이 설정 파일을 함께 커밋하면 팀에서도 같은 상태를 공유할 수 있습니다.
 
-## 명령과 옵션
+## 추가할 수 있는 코드
 
-| 명령/옵션 | 동작 |
-| --- | --- |
-| list | 설치 가능한 항목과 설명 출력 |
-| 명령 없음 / add | 카탈로그 선택 설치 시작 |
-| add <항목...> | 해당 항목을 미리 선택한 상태로 시작 |
-| --dir <경로> | 선택한 대분류들의 경로 초기값 |
-| --dry-run | 동일한 선택·검토 과정 후 예정 내역만 출력. 설정도 쓰지 않음 |
-| --overwrite | 첫 충돌 화면의 교체 후보를 미리 체크. 개별 해제와 최종 확인 가능 |
-| --help | 도움말 |
-| --version | CLI 버전 |
+| 분류 | 예시 | 용도 |
+| --- | --- | --- |
+| Core | `array-chunk`, `object-pick`, `number-lcm` | 배열·객체·문자열·숫자 처리 |
+| 알고리즘·자료구조 | `algorithm-graph-dijkstra`, `data-structure-heap` | 그래프 탐색, 힙, 큐 등 |
+| Tailwind CSS | `tailwindcss-cn`, `tailwindcss-create-tailwind-css` | 조건부 클래스와 variant 구성 |
+| FSD lint | `lint-fsd` | 레이어 의존성과 디렉터리 구조 검사 |
+
+전체 목록은 다음 명령으로 확인할 수 있습니다.
 
 ```bash
-npx @no-k/hermes@0.1.0 add array-chunk number-lcm --dir src/shared/hermes
-npx @no-k/hermes@0.1.0 add array-chunk --dir "src/my utilities" --dry-run
+npx @no-k/hermes@latest list
 ```
 
-내용이 같은 기존 파일은 유지합니다. 내용이 다른 파일도 기본은 유지이며,
-파일 검토 화면에서 Space로 교체할 파일만 체크하고 Tab으로 차이를 확인합니다.
-최종 목록에서 ↑↓로 스크롤하고, `y`/`n` 또는 Tab으로 Yes/No를 선택한 뒤 Enter로 확정합니다.
-기본 선택은 No이며 인자나 옵션을 모두 전달해도 최종 확인을 건너뛰지 않습니다.
-검토 중 파일이나 설정이 바뀌면 다시 계획하고 확인받습니다. 변경된 충돌에는 이전 교체 승인을 적용하지 않습니다.
-목적지의 심볼릭 링크를 통해 파일을 쓰지 않습니다.
+Core 유틸에는 외부 런타임 npm 의존성이 없습니다.
+라이브러리 항목에 필요한 npm 패키지는 설치 결과에 안내되므로, 사용하는 패키지 매니저로 추가하세요.
+Hermes는 프로젝트의 `package.json`과 lockfile을 자동으로 수정하지 않습니다.
 
-설치는 입력·출력이 모두 연결된 대화형 터미널에서 실행합니다. 파이프·리다이렉트 환경의
-`add`는 오류 안내로 끝나고, 명령 없이 실행하면 도움말을 출력합니다. `list`, `--help`, `--version`은
-항상 바로 출력합니다. `q` 취소는 종료 코드 0, Ctrl+C는 130, 입력 종료는 1입니다.
-경로·검색 입력 중에는 `q`도 입력 문자이므로 Ctrl+C로 중단합니다.
+`string-uuid`처럼 Node.js가 필요한 항목과 `dom-*`처럼 브라우저 DOM이 필요한 항목은
+선택 화면에서 실행 환경을 확인할 수 있습니다.
 
-## 항목과 의존성
+### Tailwind CSS 헬퍼
 
-항목 이름은 core 디렉터리 경로를 하이픈으로 연결한 이름입니다.
-Tailwind 항목에는 tailwindcss- 접두어를 붙입니다.
+`tailwindcss-cn`은 조건부 클래스를 합치고, 충돌하는 Tailwind 클래스를 정리합니다.
 
-| 항목 | 포함하는 소스 |
-| --- | --- |
-| array-chunk | 배열 분할 |
-| number-lcm | 최소공배수와 필요한 gcd |
-| algorithm-graph-dijkstra | 최단 거리와 필요한 우선순위 큐·힙 |
-| tailwindcss-cn | 클래스 병합과 설정 |
-| tailwindcss-create-tailwind-css | 설정을 공유하는 cn·classVariant |
-| string-uuid | Node.js UUID 생성 |
-
-core 항목은 외부 런타임 npm 의존성이 없습니다.
-Tailwind 항목은 clsx, tailwind-merge, tailwind-variants 중 해당 항목이 참조하는 패키지가 필요합니다.
-CLI가 필요한 설치 명령을 출력합니다. 소비 프로젝트의 패키지 매니저에 맞춰 직접 설치하세요.
-CLI는 package.json이나 lockfile을 수정하지 않습니다.
-설치 결과의 `npm install ...`은 같은 패키지·버전 범위를 유지한 채 `pnpm add ...`, `yarn add ...`,
-`bun add ...`로 바꿔 실행할 수 있습니다. `npm install --save-dev ...`는 각 도구의 `add -D ...`에
-해당합니다. 이 명령도 유틸을 사용하는 앱·패키지 디렉터리에서 실행하고 lockfile을 함께 관리하세요.
-내부 모듈의 필수 `dependencies`와 필수 `peerDependencies`는 소스로 함께 복사합니다.
-서로 import하는 모듈의 버전 범위, 기존 설치 기록, 설치된 외부 패키지의 peer 범위를 검사하고
-알려진 충돌이 있으면 파일을 쓰기 전에 중단합니다. 아직 없는 외부 패키지는 설치 명령으로 안내합니다.
-
-Node용 항목은 @types/node 설치 명령도 안내합니다.
-string-uuid는 정적 node:crypto import 때문에 Node.js에서 사용해야 합니다.
-dom-* 항목에는 DOM API와 DOM TypeScript 타입이 필요합니다.
-현재 Tailwind 헬퍼의 병합 규칙은 Tailwind CSS 4 기준입니다.
-
-## 업데이트와 라이선스
-
-새 유틸을 찾을 때는 `@latest`로 최신 CLI에 포함된 카탈로그를 탐색합니다.
-카탈로그는 실행 중 원격에서 갱신되지 않으므로 이전 버전으로 실행하면 그 버전의 항목만 보입니다.
-같은 카탈로그와 템플릿을 다시 사용하려면 CLI 버전을 확인하고 명령에서 고정하세요.
+```bash
+npx @no-k/hermes@latest add tailwindcss-cn
+npm install "clsx@^2.1.1" "tailwind-merge@^3.6.0"
+```
+
+```ts
+// styles.ts — 프로젝트 루트의 파일
+import { cn } from "./libs/hermes/tailwindcss/cn";
+
+cn("px-2 py-1", "px-4"); // "py-1 px-4"
+cn("text-sm", { "font-bold": true }); // "text-sm font-bold"
+```
+
+기본 병합 규칙은 Tailwind CSS 4를 기준으로 합니다.
+프로젝트에 맞춘 병합 설정을 `cn`과 `classVariant`에서 함께 사용하려면
+`tailwindcss-create-tailwind-css`를 선택하세요.
+
+### FSD lint 규칙
+
+`lint-fsd`는 Feature-Sliced Design의 레이어 의존 방향, 같은 레이어의 slice 간 참조,
+public API 사용과 디렉터리 구조를 검사합니다. **Hermes 0.3.0 이상**에서 사용할 수 있습니다.
 
 ```bash
-npx @no-k/hermes@latest --version
-# 확인한 버전이 0.1.0인 경우
-npx @no-k/hermes@0.1.0
-npx @no-k/hermes@0.1.0 list
+npx @no-k/hermes@latest add lint-fsd
+npm install --save-dev eslint typescript-eslint typescript "jiti@^2.2.0" "@types/node@^22"
 ```
 
-설치할 때는 `@latest`와 버전 고정 모두 선택 화면과 최종 Yes/No를 거칩니다.
-안내하는 외부 의존성은 버전 범위를 사용하므로 정확한 설치 버전은 소비 프로젝트 lockfile로 관리합니다.
-이미 복사한 소스는 새 버전이 나와도 자동 변경되지 않습니다.
-업데이트할 때는 직접 수정한 부분과 공통 보조 파일의 호환성을 함께 검토하세요.
-유틸별 버전은 CLI 배포 버전과 별개입니다. 예를 들어 `number-lcm@1.0.0`과
-`number-gcd@1.2.0`을 같은 CLI가 포함할 수 있습니다. 한 설치 위치에는 모듈별 한 버전만 둡니다.
-과거 버전을 별도로 내려받아 조합하는 기능은 제공하지 않습니다.
+기본 위치는 **`libs/hermes/lint/fsd`**입니다.
+ESLint 9 또는 10의 flat config에 생성된 플러그인을 연결하세요.
+다음은 TypeScript 프로젝트의 설정 예시입니다.
 
-각 유틸의 `package.json`과 `CHANGELOG.md`, Changesets 사용법은
-[독립 버전 관리](docs/module-versioning.md)를 참고하세요.
+```ts
+// eslint.config.ts
+import tseslint from "typescript-eslint";
+import fsd from "./libs/hermes/lint/fsd";
+
+export default [
+  ...tseslint.configs.recommended,
+  fsd.configs.recommended,
+];
+```
 
-ISC 라이선스입니다. 함께 생성되는 LICENSE의 저작권·허가 문구를 유지해 주세요.
+```bash
+npx eslint src
+```
+
+기존 ESLint 설정이 있다면 그 설정에 `fsd.configs.recommended`를 추가하세요.
+위 예시는 `jiti`로 읽는 `eslint.config.ts`용입니다. `.js`·`.mjs` 설정에 연결하는 방법은
+[FSD 사용 가이드](https://github.com/no-k/hermes/tree/main/packages/lib/lint/fsd#설치와-eslint-설정)를 참고하세요.
 
-## 개발 및 검증
+기본 검사 루트는 `src`, 경로 별칭은 `@`와 `~`입니다.
+`createConfig`로 프로젝트 구조에 맞춰 설정하거나, 생성된 `options.ts`와 `rules/`를 직접 수정할 수 있습니다.
+[프로젝트별 옵션과 Oxlint 사용법](https://github.com/no-k/hermes/tree/main/packages/lib/lint/fsd)도 제공합니다.
 
-CLI 소스와 관련 도구는 이 패키지 안에서 TypeScript로 관리합니다.
+## 생성 위치 지정하기
 
-| 경로 | 역할 |
+| 분류 | 기본 경로 |
 | --- | --- |
-| `src/bin/hermes.ts` | 대화형 설치 진입, 조회 명령과 결과 출력 |
-| `src/lib/install-wizard.ts` | 선택·경로·충돌·최종 확인 연결과 변경된 계획 재검토 |
-| `src/lib/install-prompts.ts`, `install-view.tsx` | 경로 입력과 스크롤 가능한 최종 Yes/No 화면 |
-| `src/lib/install.ts` | 쓰기 없는 설치 계획 계산, 파일별 충돌 결정, 설정 저장을 포함한 실행 |
-| `src/lib/files.ts` | 목적지 검사, 계획 이후 변경 감지와 파일 쓰기 |
-| `src/lib/project-config.ts`, `config-syntax.ts` | 설정 읽기·검증, 원문 보존 갱신과 설치 목록 병합 |
-| `src/lib/report.ts` | 파일 결과·외부 의존성·실행 환경 안내 |
-| `src/lib/catalog.ts`, `json.ts` | catalog 타입과 JSON 검증 |
-| `src/lib/catalog-query.ts` | 분류 계층 조회, 이름·전체 설명 검색, 분류 필터와 표시용 요약 |
-| `src/lib/catalog-selection.ts` | 대분류·하위 분류·유틸 선택과 이전 선택 복원 |
-| `src/lib/picker.ts`, `picker-view.tsx`, `terminal.ts`, `terminal-text.ts` | 선택 상태, Ink 화면, 터미널 입력과 화면 복원 |
-| `src/lib/installation-status.ts` | 설치 기록과 실제 파일을 대조한 상태·위치 표시 |
-| `src/lib/conflict-selection.ts` | 기존 파일과 생성 후보의 차이 검토, 파일별 유지·교체 선택 |
-| `src/lib/versions.ts` | 실제 파일 해시와 설치 버전 대조, 내부 의존성·외부 peer 호환성 검사 |
-| `scripts/catalog-lib.ts` | 유틸 탐색, 의존성 추적과 README 설명 추출 |
-| `scripts/build-cli.ts` | catalog와 템플릿 생성 |
-| `scripts/version-modules.ts` | Changesets 버전 적용 시 유틸 변경을 CLI 배포 버전에 연결 |
-| `scripts/preview-ui.ts` | 파일을 생성하지 않는 개발용 선택 화면 미리보기 |
-| `scripts/pack-cli.ts` | npm tarball 생성 및 포함 파일 검증 |
-| `scripts/smoke-cli.ts` | tarball을 설치해 소비 프로젝트에서 컴파일·실행 |
-| `test/*.test.ts` | CLI·catalog·패키징 회귀 테스트 |
-
-대화형 설치는 [단계별 계약](docs/interactive-install.md)에 따라 설치 엔진·설정, 카탈로그 탐색,
-독립 모듈 버전 관리와 터미널 선택 화면을 연결합니다.
-`hermes`와 `hermes add` 모두 대화형 선택 후 최종 Yes에서 설치하고 설정과 버전을 저장합니다.
-
-개발용 화면은 다음 명령으로 확인할 수 있습니다. 선택 결과를 표시하고 파일을 생성하지 않습니다.
-매번 전체 빌드하지 않고 `tsx`로 화면 소스를 실행합니다. 기존 catalog.json을 읽으며,
-아직 빌드하지 않았다면 소스에서 카탈로그를 메모리에 구성합니다.
+| Core | `src/utils/hermes` |
+| 라이브러리 — Tailwind CSS, lint | `libs/hermes` |
+
+경로는 선택 화면에서 바꾸거나 `--dir`로 지정할 수 있습니다.
+그 아래에는 `array/chunk`, `lint/fsd`처럼 항목별 폴더 구조가 만들어집니다.
 
 ```bash
-pnpm --filter @no-k/hermes run preview:ui
-# 초기 선택값을 넣어 탐색할 수도 있습니다.
-pnpm --filter @no-k/hermes run preview:ui number-lcm tailwindcss-cn
-# 결과와 재진입 상태를 JSON으로 확인합니다.
-pnpm --filter @no-k/hermes run preview:ui --json number-lcm
+npx @no-k/hermes@latest add array-chunk number-lcm --dir src/shared/hermes
+npx @no-k/hermes@latest add lint-fsd --dir libs/hermes
 ```
 
-현재 단계, 포커스, 체크 수를 색상으로 구분합니다. 101열 이상에서는 목록 옆에 상세 패널이
-표시되고, 좁거나 낮은 터미널에서는 한 열로 전환합니다. 키 입력을 즉시 선택 상태에 반영하고
-연속 입력의 화면 갱신을 합칩니다. 바뀐 줄만 최대 60fps로 출력해 전체 화면 지우기를 줄입니다.
+경로는 **`--dir` → 현재 프로젝트에 저장된 설정 → 기본값** 순서로 적용합니다.
+이전에 다른 경로를 사용했다면 `--dir libs/hermes`로 라이브러리 위치를 다시 지정할 수 있습니다.
+공백이 포함된 경로는 따옴표로 감싸세요.
 
-대분류 → 각 대분류의 하위 분류 → 각 하위 분류의 유틸 순서로 선택합니다.
-↑↓로 이동하고 Space로 체크하며 Enter로 다음 화면에 갑니다. `/`로 검색을 시작하고
-Enter로 검색 입력을 끝냅니다. Tab은 상세 보기, Esc는 상세·검색 닫기 또는 이전 화면,
-`a`는 검색 결과 전체 선택·해제, Ctrl+L은 검색 초기화, `q`는 취소입니다.
-목록에서는 `j`/`k`로도 이동할 수 있습니다. 한국어 검색과 bracketed paste를 지원합니다.
-분류를 해제하면 그 안의 선택은 설치 대상에서 제외되고, 다시 선택하면 체크가 복원됩니다.
-상세 화면에서 함께 생성되는 의존 모듈, npm·peer 의존성, 실행 환경과 기존 설치 위치를 확인할 수 있습니다.
+모노레포에서는 코드를 사용할 앱이나 패키지 디렉터리에서 실행하세요.
+각 디렉터리의 `no-k.config.ts`로 설치 위치를 관리합니다.
 
-미리보기는 실행 디렉터리의 설정을 읽습니다. 위 pnpm 명령의 실행 디렉터리는 `packages/cli`입니다.
-다른 앱의 설치 기록을 보려면 CLI를 빌드한 뒤 그 앱 디렉터리에서
-`node /저장소/절대경로/packages/cli/.build/scripts/preview-ui.js`를 실행합니다.
+## 수정한 코드와 업데이트
 
-설정 모듈은 `export default { ... }`의 데이터 리터럴, 주석, 마지막 쉼표, 최상위 `as const`를
-지원합니다. 사용자 필드와 주석을 보존하기 위해 필요한 값만 수정하며, import·함수·변수 참조 등
-지원하지 않는 구문은 위치를 안내하고 원본을 유지합니다. 설정 파일의 코드를 실행하지 않습니다.
+생성된 소스는 자유롭게 수정할 수 있습니다. Hermes의 새 버전이 나와도 기존 파일이 자동으로 바뀌지 않습니다.
 
-저장소 루트에서 실행합니다.
+업데이트하려면 최신 CLI에서 같은 항목을 다시 선택하세요.
+내용이 다른 파일은 기본적으로 유지되며, 차이를 확인한 뒤 교체할 파일만 고를 수 있습니다.
+실제 파일을 쓰기 전에 확인하려면 `--dry-run`을 사용하세요.
 
 ```bash
-pnpm install --frozen-lockfile
-pnpm run build:cli
-pnpm run check
-pnpm run test:run
-pnpm run check:cli
-pnpm run pack:cli
-pnpm run test:cli-install
+npx @no-k/hermes@latest add lint-fsd --dry-run
 ```
 
-`tsconfig.json`은 런타임·도구·테스트 전체를 strict 및 `noUncheckedIndexedAccess`로 검사합니다.
-NodeNext 모듈 해석과 ES2022 출력을 사용하며, 상대 import에는 `.js` 확장자를 씁니다.
-`tsconfig.build.json`은 런타임을 `dist/`에, `tsconfig.tools.json`은 도구·테스트와 참조하는
-공유 모듈을 `.build/`에 컴파일합니다. 타입 오류가 있으면 해당 컴파일의 출력은 생성되지 않습니다.
-
-빌드는 이전 `dist/`, `.build/`, `templates/`, `catalog.json`을 지우고 컴파일한 다음
-catalog와 템플릿을 생성합니다. 항목 설명은 각 유틸 README의 첫 문단 전체에서 가져옵니다.
-생성된 catalog를 직접 수정하지 말고 해당 README를 수정하세요.
-
-카탈로그 스키마 3은 각 항목의 `scope`(core/lib)와 `category`(core/array, lib/tailwindcss 등)를
-원본 진입 경로에서 생성합니다. Core의 하위 분류와 `packages/lib`의 라이브러리 패키지를 빌드 시
-탐색하므로 새 유틸이나 분류가 자동 반영됩니다. 유틸 ID나 보조 파일 순서로 소속을 추측하지 않습니다.
-각 모듈의 manifest에서 패키지 이름·버전·의존 범위를 읽고, 함께 복사하는 모듈과 파일 해시를 기록합니다.
-프로젝트 설정인 no-k.config.ts의 스키마는 1을 유지하며 기존 위치 기록도 읽을 수 있습니다.
-
-`filterCatalog`는 이름·소개 문단 전체 검색과 대분류·하위 분류 필터를 조합합니다.
-검색어를 공백으로 나누어 모두 일치하는 항목을 찾으며, 한글 Unicode 표현과 영문 대소문자를
-정규화합니다. `getCatalogGroups`는 같은 결과를 대분류별 하위 분류와 유틸 목록으로 구성합니다.
-필터 생략은 전체 조회, 빈 배열은 선택 없음입니다. `summarizeDescription`의 화면용 요약은
-전체 설명이나 검색 결과를 바꾸지 않습니다. 선택 화면은 이 조회 함수들을 재사용하며,
-검색 결과 밖에 있는 체크도 유지하고 전체 선택 수를 표시합니다.
-
-`check:cli`, `pack:cli`, `test:cli-install`은 빌드부터 실행합니다.
-직접 `npm pack` 또는 `pnpm pack`을 실행해도 `prepack`이 같은 빌드를 수행합니다.
-검증 스크립트 내부의 `npm pack --ignore-scripts`는 이미 빌드한 결과를 포장해 중복 빌드를 피합니다.
-
-npm 패키지에는 `dist/`의 ESM JavaScript, `catalog.json`, `templates/`의 TypeScript 유틸,
-README·LICENSE·package.json이 포함됩니다. CLI TypeScript 소스, 개발 도구와 테스트는 포함하지 않습니다.
-TypeScript·타입 패키지·tsx는 개발 의존성이며, 배포된 CLI의 직접 런타임 의존성은
-`ink`, `react`, `semver`입니다. 소비 프로젝트에 생성되는 유틸에는 UI 의존성을 추가하지 않습니다.
-`pack:cli`는 `artifacts/`에 tarball을 만들고 파일 목록·실행 권한을 검사합니다.
-`test:cli-install`은 그 tarball을 별도 소비 프로젝트에서 검증하며 npm에 배포하지 않습니다.
-첫 `npx` 실행은 런타임 의존성을 내려받고, 다음 실행은 같은 캐시에서 오프라인으로 검증합니다.
-PTY 통합 검증은 macOS·Linux의 `script` 명령으로 실제 터미널 입력을 전달합니다.
-한국어 탐색과 여러 분류 선택, 별도 경로 저장·재사용, No 이후 파일별 결정 유지,
-최종 확인 중 파일 변경, 화면별 취소, 입력·출력 각각의 리다이렉트를 검사합니다.
-최종 Yes 이전에는 파일이 생기거나 기존 파일이 바뀌지 않는지도 실제 실행 중 확인합니다.
-Windows에서는 이 PTY 테스트를 건너뛰며 `test:cli-install`은 macOS·Linux에서 실행합니다.
+팀에서 같은 CLI 버전을 사용하려면 버전을 명시할 수 있습니다.
+
+```bash
+npx @no-k/hermes@0.3.0 add lint-fsd
+```
+
+항목에 필요한 공통 보조 파일도 함께 생성됩니다.
+여러 유틸이 공유하는 코드를 수정했다면 업데이트할 때 함께 사용하는 유틸도 확인하세요.
+
+## 명령어
+
+| 명령·옵션 | 설명 |
+| --- | --- |
+| `npx @no-k/hermes@latest` | 전체 목록에서 선택 시작 |
+| `add <항목...>` | 지정한 항목을 미리 선택 |
+| `list` | 전체 항목과 설명 출력 |
+| `--dir <경로>` | 생성 위치 지정 |
+| `--dry-run` | 파일과 설정을 쓰지 않고 설치 계획 확인 |
+| `--overwrite` | 파일 검토 화면에서 교체 후보를 미리 선택 |
+| `--help` | 도움말 |
+| `--version` | CLI 버전 확인 |
+
+설치는 대화형 터미널에서 진행합니다. `--overwrite`를 사용해도 최종 확인 단계는 유지됩니다.
+
+## 더 알아보기
+
+- [FSD 설정과 Oxlint 사용법](https://github.com/no-k/hermes/tree/main/packages/lib/lint/fsd)
+- [변경 이력](https://github.com/no-k/hermes/blob/main/packages/cli/CHANGELOG.md)
+- [문제 신고·기능 제안](https://github.com/no-k/hermes/issues)
+- [기여자를 위한 개발 가이드](https://github.com/no-k/hermes/blob/main/packages/cli/docs/development.md)
+
+## 라이선스
+
+[ISC](https://github.com/no-k/hermes/blob/main/packages/cli/LICENSE). 생성된 코드와 함께 제공되는 `LICENSE`의 저작권·허가 문구를 유지해 주세요.

package/catalog.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 3,
-  "version": "0.2.0",
+  "version": "0.3.2",
   "items": [
     {
       "name": "algorithm-geometry-ccw",
@@ -1726,6 +1726,54 @@
         "http/status/status.ts"
       ]
     },
+    {
+      "name": "lint-fsd",
+      "packageName": "@hermes/lint-fsd",
+      "version": "0.1.0",
+      "modules": [
+        {
+          "name": "lint-fsd",
+          "packageName": "@hermes/lint-fsd",
+          "version": "0.1.0",
+          "scope": "lib",
+          "files": {
+            "lint/fsd/fsd.ts": "7bca7aae487a8d2bad71f2d152b8420a2cd7a8259c514224b6df764fe7642164",
+            "lint/fsd/import-listener.ts": "b07c96183e23f6e8902b1451fc350cd0eb5e87c0ed77626376fffa870c6434bc",
+            "lint/fsd/index.ts": "b5a08b38570e5094eacf089ecbe5bf0ac12692671bc266c923796172b8a436a8",
+            "lint/fsd/options.ts": "e24e3fb0cf0ab12cda93614ae19fcd1762d2b23c746a087390f612113195193b",
+            "lint/fsd/rules/fsd-layer-imports.ts": "23cee966cf7d230e2762c70d5c115fc49a26a9ccf8ba33a2d2bedb41f244ea0d",
+            "lint/fsd/rules/fsd-public-api.ts": "474eb3d91081db8b31a678990c19ddda346125a54c1a10a7cf7d2ed07eb41b28",
+            "lint/fsd/rules/fsd-slice-segments.ts": "57d72120b747d4d091ae09abc99e8f821c7ebca1ee4e992d1fc9fe1ab29ad275"
+          },
+          "requires": [
+            {
+              "packageName": "eslint",
+              "range": "^9.0.0 || ^10.0.0",
+              "kind": "peer",
+              "internal": false,
+              "optional": true
+            }
+          ]
+        }
+      ],
+      "scope": "lib",
+      "category": "lib/lint",
+      "description": "Feature-Sliced Design의 레이어 의존 방향, slice 경계, public API와 디렉터리 구조를 검사합니다. Hermes CLI가 규칙의 TypeScript 소스를 프로젝트에 생성합니다. 생성된 파일은 자유롭게 수정할 수 있습니다.",
+      "dependencies": [],
+      "runtime": "node",
+      "devDependencies": [
+        "@types/node@^22"
+      ],
+      "files": [
+        "lint/fsd/fsd.ts",
+        "lint/fsd/import-listener.ts",
+        "lint/fsd/index.ts",
+        "lint/fsd/options.ts",
+        "lint/fsd/rules/fsd-layer-imports.ts",
+        "lint/fsd/rules/fsd-public-api.ts",
+        "lint/fsd/rules/fsd-slice-segments.ts"
+      ]
+    },
     {
       "name": "number-clamp",
       "packageName": "@hermes/number-clamp",

package/dist/bin/hermes.js

@@ -25,7 +25,7 @@ const help = [
     "  -h, --help      Show help",
     "  -v, --version   Show version",
     "",
-    "Defaults: Core → src/utils/hermes; libraries → src/lib/hermes.",
+    "Defaults: Core → src/utils/hermes; libraries → libs/hermes.",
     "Saved paths are read from no-k.config.ts in the current directory.",
     "Run in an interactive terminal; choose No to edit your selection.",
     "External npm dependencies are reported; they are not installed automatically.",

package/dist/lib/barrel.js

@@ -0,0 +1,77 @@
+import path from "node:path";
+import { readDestination } from "./files.js";
+import { resolveInstallDirectory } from "./project-config.js";
+function appendExports(existing, entries) {
+    // 이미 내보내는 경로를 확인하되 주석과 문자열 안의 예시는 export로 취급하지 않는다.
+    const exports = new Set([
+        ...existing.matchAll(/\/\/[^\r\n]*|\/\*[\s\S]*?\*\/|"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`(?:\\.|[^`\\])*`|\bexport\s*\*\s*from\s*["']([^"'\r\n]+)["']/g),
+    ].flatMap((match) => (match[1] ? [match[1].replace(/\/index(?:\.[jt]s)?$/, "")] : [])));
+    const missing = entries.filter((entry) => !exports.has(entry));
+    if (!missing.length)
+        return existing;
+    const newline = existing.includes("\r\n") ? "\r\n" : "\n";
+    return (existing +
+        (existing && !existing.endsWith("\n") ? newline : "") +
+        missing.map((entry) => "export * from " + JSON.stringify(entry) + ";" + newline).join(""));
+}
+export function planBarrelFiles(request, catalog, sourceFiles, compatibilityGuards) {
+    const cwd = path.dirname(request.config.destination);
+    const roots = new Map();
+    const planned = new Set(sourceFiles.map((file) => file.destination));
+    const guards = new Map(compatibilityGuards.map((file) => [file.destination, file]));
+    for (const target of request.targets) {
+        const directory = resolveInstallDirectory(target.directory, cwd);
+        const entries = roots.get(directory) ?? new Set();
+        for (const item of catalog.items.filter((item) => target.names.includes(item.name)))
+            for (const file of item.files)
+                if (file.endsWith("/index.ts"))
+                    entries.add(file);
+        roots.set(directory, entries);
+    }
+    // 배럴을 만들지 않던 버전의 설치도 복원한다. 다른 목적지의 설치 기록은 섞지 않는다.
+    for (const record of request.config.status === "loaded" ? request.config.value.installed : []) {
+        const entries = roots.get(resolveInstallDirectory(record.directory, cwd));
+        if (entries) {
+            const files = record.source
+                ? record.source.modules.flatMap((module) => Object.keys(module.files))
+                : (catalog.items.find((item) => item.name === record.name && item.scope === record.scope)?.files ?? []);
+            for (const file of files)
+                if (file.endsWith("/index.ts"))
+                    entries.add(file);
+        }
+    }
+    const files = [];
+    for (const [directory, candidates] of roots) {
+        const entries = [...candidates].sort().flatMap((file) => {
+            const destination = path.join(directory, file);
+            if (!planned.has(destination)) {
+                let guard = guards.get(destination);
+                if (!guard) {
+                    const existingContent = readDestination(destination);
+                    guard = {
+                        file,
+                        destination,
+                        existingContent,
+                        content: existingContent ?? "",
+                        action: existingContent === null ? "create" : "keep",
+                    };
+                    guards.set(destination, guard);
+                }
+                if (guard.existingContent === null)
+                    return [];
+            }
+            return ["./" + file.slice(0, -"/index.ts".length)];
+        });
+        const destination = path.join(directory, "index.ts");
+        const existingContent = readDestination(destination);
+        const content = appendExports(existingContent ?? "", entries);
+        files.push({
+            file: "index.ts",
+            destination,
+            content,
+            existingContent,
+            action: existingContent === null ? "create" : existingContent === content ? "keep" : "replace",
+        });
+    }
+    return { files, compatibilityGuards: [...guards.values()] };
+}

package/dist/lib/contracts.js

@@ -1,4 +1,4 @@
 export const DEFAULT_INSTALL_DIRECTORIES = Object.freeze({
     core: "src/utils/hermes",
-    lib: "src/lib/hermes",
+    lib: "libs/hermes",
 });

package/dist/lib/install.js

@@ -1,5 +1,6 @@
 import { readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
+import { planBarrelFiles } from "./barrel.js";
 import { isSourcePath, isUtilityScope } from "./catalog.js";
 import { readDestination, validateFilePlans, writePlannedFile } from "./files.js";
 import { PROJECT_CONFIG_FILENAME, mergeProjectConfig, planProjectConfig, resolveInstallDirectory, } from "./project-config.js";
@@ -126,15 +127,19 @@ export function createInstallPlan(request, catalog, packageDirectory) {
     const utilities = planUtilityFiles(targets, packageDirectory, request.fileDecisions);
     const { config, dependencies, compatibilityErrors, compatibilityGuards } = planInstalledVersions(mergeProjectConfig(request.config, request.targets), targets, utilities.files, catalog, cwd);
     const configFile = planProjectConfig(request.config, config);
-    validateFilePlans([...utilities.files, configFile]);
+    const barrels = planBarrelFiles(request, catalog, utilities.files, compatibilityGuards);
+    const files = [...utilities.files, ...barrels.files].sort((a, b) => a.destination.localeCompare(b.destination));
+    validateFilePlans(barrels.compatibilityGuards);
+    validateFilePlans([...files, configFile]);
     return {
         ...request,
         ...utilities,
+        files,
         dependencies,
         configFile,
         nextConfig: config,
         compatibilityErrors,
-        compatibilityGuards,
+        compatibilityGuards: barrels.compatibilityGuards,
     };
 }
 export class InstallExecutionError extends Error {