create-harness-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yk/side-project
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# create-harness
+
+> 기존 프로젝트에 AI 코딩 에이전트 하네스를 한 명령으로 얹는다.
+
+`create-harness`는 앱을 새로 만드는 스캐폴더가 아니라, **이미 있는 프로젝트**에
+AI 에이전트(Cursor, Claude Code)가 일관된 결과물을 내도록 하는 하네스를 설치하는 CLI다.
+
+> npm의 `create-harness` 이름은 무관한 다른 패키지가 선점하고 있어, 배포명은
+> `create-harness-cli`다. 저장소·CLI 브랜드명은 그대로 `create-harness`를 쓴다.
+
+```bash
+npx create-harness-cli            # 현재 디렉터리에
+npx create-harness-cli ./my-app --yes --dry-run   # 계획만 확인
+```
+
+## 무엇이 생기나
+
+두 축으로 구성된다.
+
+**축 1 — 코딩 컨벤션** (에이전트가 무엇을 모방할지)
+
+- `AGENTS.md` — 모든 도구가 읽는 짧은 정본. `CLAUDE.md` 는 `@AGENTS.md` 임포트 한 줄
+- `.cursor/rules/*.mdc` 6종 — 레이어·명명·상태 4분류·디자인시스템·테스트·인증 규칙 (globs 조건부 로드)
+- 참조 구현 — axios 인터셉터(refresh 중복 제거)·`ProtectedRoute`·queries 3계층·Zustand 스토어.
+  산문 문서가 아니라 **컴파일되는 코드**라서 에이전트가 실제로 모방한다
+
+**축 2 — 검증 게이트** (문서가 아니라 게이트로 강제)
+
+- `.harness/config.json` — 프로젝트가 통과해야 하는 `checks` 목록 (대상 package.json 의
+  scripts 를 감지해 실제 존재하는 것만 담는다)
+- 커밋 게이트 — 같은 스크립트 하나를 Cursor(`beforeShellExecution`)와
+  Claude Code(`PreToolUse`) 양쪽에 연결. checks 실패·`.env` 스테이징·force push 시 커밋 거부
+- 워크플로 6종 — `/spec`(명세) → `/impl`(테스트 우선 구현) → `/verify` → `/ship`,
+  UI 작업은 `/ds-init`(Storybook 온디맨드 설치)·`/ds-add`(레이아웃 전 컴포넌트 선행)
+- 린트 강제 — 명명 규칙(`I` 접두 등)·공개 API 경계·색상 원시값 차단(stylelint)을 error 처리
+
+## 옵션
+
+```
+npx create-harness-cli [대상 디렉터리] [옵션]
+
+--preset <name>     프리셋 (v0.1: react-fe)
+--agents <csv>      cursor,claude (기본: 둘 다)
+--modules <csv>     design-system,auth-http,data-fetching,lint (기본: 감지 결과에 따름)
+--ponytail          서드파티 ponytail 규칙(YAGNI 사다리) 연동 (기본: 끔)
+--dry-run           파일을 쓰지 않고 계획만 출력
+-y, --yes           질문 없이 진행
+```
+
+## 모듈 기본값은 감지 결과가 정한다
+
+코어(규칙·워크플로·게이트·docs)는 항상 설치되지만, **코드를 생성하는 모듈**은
+대상 프로젝트에서 그대로 컴파일·통과하는 것만 기본 선택됩니다.
+기준은 하나입니다 — 설치 직후 검증이 깨지지 않는가.
+
+| 모듈 | 기본 선택 조건 | 빠지는 경우 |
+|---|---|---|
+| `design-system` | CSS / CSS Modules | Tailwind, CSS-in-JS (stylelint가 값에 닿지 못함) |
+| `auth-http` | axios + react-router + Vite | fetch만 쓰거나 Next.js/CRA |
+| `data-fetching` | TanStack Query + Zustand + axios | SWR·Redux 등 다른 조합 |
+| `lint` | ESLint flat config + TypeScript | 구형 `.eslintrc`, JS 전용 |
+
+빠진 모듈은 이유와 함께 출력되고, `--modules` 로 명시하면 강제로 포함됩니다.
+대화형 실행에서는 비권장 모듈도 `(비권장)` 표시와 근거를 달고 목록에 나오므로 직접 켤 수 있습니다.
+
+모듈을 빼면 **그 모듈을 전제하는 규칙·워크플로도 함께 빠집니다.** 예를 들어
+`design-system` 없이 설치하면 `30-design-system` 규칙, `/ds-init`·`/ds-add` 워크플로,
+`AGENTS.md` 의 해당 항목이 모두 생성되지 않습니다. 존재하지 않는 파일을 가리키는
+규칙은 에이전트를 헷갈리게 할 뿐입니다.
+
+## 디자인시스템에 대한 입장
+
+`design-system` 모듈은 웬만하면 켜는 것을 권장합니다. AI 에이전트가 화면마다 다른
+색·간격을 쓰는 UI 드리프트를 막는 **결정적**(deterministic) 수단이 토큰 + stylelint
+하나뿐이기 때문입니다. 규칙 문서는 확률적으로만 지켜집니다.
+
+같은 이유로 이 하네스는 **Tailwind 를 권장하지 않습니다.** 값이 클래스 문자열 안에
+있어 stylelint 가 닿지 못하고, 임의값(`bg-[#3b82f6]`)을 막으려면 별도의 ESLint 규칙
+체계를 따로 유지해야 합니다. 새 프로젝트라면 CSS Modules + `tokens.css` 를 권장합니다.
+
+### 기존 프로젝트의 stylelint 유예
+
+이미 색상 원시값을 쓰는 CSS가 있는 프로젝트에 토큰 강제를 error로 얹으면 첫 커밋부터
+수백 건이 막혀 결국 게이트를 꺼버리게 됩니다. 그래서 설치 시점에 원시값을 쓰던 파일만
+`.harness/stylelint-baseline.json` 에 올려 **그 파일들만 warning** 으로 낮춥니다.
+새로 만드는 CSS는 그대로 error입니다. 정리할 때마다 목록에서 경로를 지우고, 비면
+`stylelint.config.js` 의 `overrides` 를 삭제하면 됩니다.
+
+## eslint ignores 자동 패치
+
+`.harness/` 안의 게이트 스크립트는 Node 인프라 코드라 호스트의 브라우저용 lint 설정에
+걸립니다. 그래서 설치 시 대상의 flat config(`eslint.config.*`)에 아래를 끼워 넣습니다.
+
+```js
+// create-harness: 하네스 생성 파일은 호스트 lint 대상이 아니다
+{ ignores: ['.harness/**'] },
+```
+
+`export default [`, `export default tseslint.config(`, `export default defineConfig([`
+형태를 인식하며, 이미 적용돼 있으면 아무것도 하지 않습니다(멱등). 알아보지 못하는
+형태면 파일을 건드리지 않고 붙여넣을 조각만 출력합니다.
+
+## 충돌 처리
+
+이미 존재하는 파일(`AGENTS.md` 등)은 덮어쓰지 않는다. `.harness/incoming/` 아래
+같은 경로에 두고 diff 명령을 안내한다. 재실행 시 동일 내용이면 건너뛴다(멱등).
+
+모든 생성 파일은 `.harness/manifest.json` 에 sha256과 함께 기록된다.
+(v0.2의 `update` 명령이 이 해시로 로컬 수정 여부를 구분해 3-way 병합할 예정)
+
+## Storybook은 왜 미리 설치하지 않나
+
+UI 작업이 없는 저장소에 Playwright 바이너리까지 끌고 들어오고, `.storybook/main.ts` 는
+프레임워크마다 달라 손으로 쓴 템플릿이 빠르게 낡는다. 대신 `/ds-init` 워크플로가
+필요해진 시점에 공식 CLI로 설치하고, a11y 위반을 검증 실패(`a11y.test = 'error'`)로
+등록한다. 자세한 근거는 `DECISIONS.md`.
+
+## ponytail 연동 (`--ponytail`)
+
+[ponytail](https://github.com/DietrichGebert/ponytail)은 이 하네스와 무관한 서드파티
+규칙으로, "YAGNI 사다리"를 강제해 에이전트가 과설계하지 않고 최소 구현을 하도록 만든다.
+`--ponytail`(또는 대화형 확인)을 켜면:
+
+- **Cursor**: 최신 GitHub 릴리스 태그에서 `.cursor/rules/ponytail.mdc` 를 실행 시점에
+  받아와 자동 설치한다. `templates/` 에 벤더링하지 않는다 — 릴리스 태그가 아니라
+  `main` 브랜치를 그대로 받으면 재실행마다 결과가 달라져 이 CLI의 멱등성 원칙과
+  어긋나고, 손으로 복사해 두면 ponytail 쪽 업데이트를 우리가 계속 따라가야 한다.
+  네트워크·API 실패 시에는 파일을 건너뛰고 수동 설치 안내로 폴백한다(스캐폴딩 전체를
+  막지 않는다).
+- **Claude Code**: `/plugin` 설치는 살아있는 세션 안에서만 실행되는 명령이라 이 CLI가
+  대신 실행할 수 없다. 대신 두 줄짜리 설치 명령을 "다음 단계" 맨 위에 출력한다.
+
+## Storybook은 왜 미리 설치하지 않나
+
+```bash
+npm run check   # typecheck → build → test
+npm run dev -- <대상경로> --yes --dry-run
+```
+
+- `templates/` 아래가 대상 프로젝트로 복사되는 산출물, 나머지는 CLI 자체 코드
+- 남은 작업: `TODO.md` / 설계 근거: `DECISIONS.md`

package/dist/cli.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { detect } from './detect.js';
+import { writeActions, writeManifest } from './manifest.js';
+import { runPrompts } from './prompts.js';
+import { patchEslintIgnores } from './eslintPatch.js';
+import { buildPonytailAction } from './ponytail.js';
+import { buildPlan, hasStylelintBaseline, requiredDevDeps } from './registry.js';
+import { recommendedModules, suggestModules } from './suggest.js';
+const VALID_AGENTS = ['cursor', 'claude'];
+const VALID_MODULES = [
+    'design-system',
+    'auth-http',
+    'data-fetching',
+    'lint',
+];
+const getOwnVersion = () => {
+    const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+    return JSON.parse(readFileSync(pkgPath, 'utf-8'))
+        .version;
+};
+const parseCsv = (raw, valid, label) => {
+    if (raw === undefined)
+        return undefined;
+    const values = raw
+        .split(',')
+        .map((value) => value.trim())
+        .filter(Boolean);
+    for (const value of values) {
+        if (!valid.includes(value)) {
+            console.error(`알 수 없는 ${label}: "${value}" (가능한 값: ${valid.join(', ')})`);
+            process.exit(1);
+        }
+    }
+    return values;
+};
+const main = async () => {
+    const { values, positionals } = parseArgs({
+        options: {
+            preset: { type: 'string', default: 'react-fe' },
+            agents: { type: 'string' },
+            modules: { type: 'string' },
+            ponytail: { type: 'boolean', default: false },
+            'dry-run': { type: 'boolean', default: false },
+            yes: { type: 'boolean', short: 'y', default: false },
+            install: { type: 'boolean', default: false },
+            help: { type: 'boolean', short: 'h', default: false },
+            version: { type: 'boolean', short: 'v', default: false },
+        },
+        allowPositionals: true,
+    });
+    if (values.version) {
+        console.log(getOwnVersion());
+        return;
+    }
+    if (values.help) {
+        console.log(`사용법: npx create-harness-cli [대상 디렉터리] [옵션]
+
+옵션:
+  --preset <name>     프리셋 (기본: react-fe)
+  --agents <csv>      cursor,claude (기본: 둘 다)
+  --modules <csv>     design-system,auth-http,data-fetching,lint
+  --ponytail          서드파티 ponytail 규칙(YAGNI 사다리) 연동
+  --dry-run           파일을 쓰지 않고 계획만 출력
+  -y, --yes           질문 없이 기본값/옵션값으로 진행
+  --install           필요한 devDependency 설치 명령까지 출력 후 실행 안내
+  -h, --help          도움말
+  -v, --version       버전`);
+        return;
+    }
+    if (values.preset !== 'react-fe') {
+        console.error(`v0.1은 react-fe 프리셋만 지원합니다 (받은 값: ${values.preset})`);
+        process.exit(1);
+    }
+    const targetDir = path.resolve(positionals[0] ?? '.');
+    const detected = detect(targetDir);
+    if (!detected.hasPackageJson) {
+        console.error(`대상에 package.json이 없습니다: ${targetDir}\n` +
+            'create-harness는 기존 프로젝트에 하네스를 얹는 도구입니다.');
+        process.exit(1);
+    }
+    const suggestions = suggestModules(detected);
+    const explicitModules = parseCsv(values.modules, VALID_MODULES, 'module');
+    const defaults = {
+        targetDir,
+        preset: 'react-fe',
+        agents: parseCsv(values.agents, VALID_AGENTS, 'agent') ?? [
+            'cursor',
+            'claude',
+        ],
+        // --modules 를 주지 않으면 감지 결과가 기본값을 정한다
+        modules: explicitModules ?? recommendedModules(detected),
+        ponytail: values.ponytail ?? false,
+        dryRun: values['dry-run'],
+        yes: values.yes,
+        install: values.install,
+    };
+    const options = await runPrompts(detected, defaults, suggestions);
+    // 감지 때문에 빠진 모듈은 이유를 남긴다 (--yes 로 프롬프트를 건너뛴 경우 특히)
+    const excluded = suggestions.filter((suggestion) => !suggestion.isRecommended &&
+        !options.modules.includes(suggestion.module));
+    if (explicitModules === undefined && excluded.length > 0) {
+        console.log(`\n${pc.dim('감지 결과로 제외된 모듈:')}`);
+        for (const suggestion of excluded) {
+            console.log(`  ${pc.dim('-')} ${suggestion.module} — ${pc.dim(suggestion.reason)}`);
+        }
+        console.log(pc.dim(`  포함하려면: --modules ${VALID_MODULES.join(',')}`));
+    }
+    // 이 하네스는 디자인시스템 모듈을 기본 전제로 삼는다 — 빠진 채로 넘어가지 않게 짚는다
+    if (!options.modules.includes('design-system')) {
+        const lines = [
+            `\n${pc.yellow('권고')} — design-system 모듈 없이 진행합니다.`,
+            pc.dim('  이 하네스가 UI 드리프트를 막는 유일한 결정적 수단이 토큰 + stylelint 입니다.\n' +
+                '  규칙 문서만으로는 에이전트가 화면마다 다른 색·간격을 씁니다.'),
+        ];
+        if (detected.hasTailwind) {
+            lines.push(pc.dim('  Tailwind 는 값이 클래스 문자열 안에 있어 stylelint 가 닿지 못합니다.\n' +
+                '  새 프로젝트라면 CSS Modules + tokens.css 조합을 권장합니다.'));
+        }
+        console.log(lines.join('\n'));
+    }
+    const plan = buildPlan(detected, options);
+    let ponytailTag = null;
+    let ponytailFetchFailed = false;
+    if (options.ponytail && options.agents.includes('cursor')) {
+        const fetched = await buildPonytailAction();
+        if (fetched) {
+            plan.push(fetched.action);
+            ponytailTag = fetched.tag;
+        }
+        else {
+            ponytailFetchFailed = true;
+        }
+    }
+    const results = writeActions(plan, targetDir, options.dryRun);
+    writeManifest(results, options, getOwnVersion(), options.dryRun);
+    const written = results.filter((result) => !result.placedInIncoming);
+    const incoming = results.filter((result) => result.placedInIncoming);
+    const header = options.dryRun
+        ? pc.yellow('[dry-run] 실제로 쓰지 않은 계획입니다')
+        : pc.green('생성 완료');
+    console.log(`\n${header} — ${detected.projectName} (${options.preset})`);
+    for (const result of written) {
+        console.log(`  ${pc.green('+')} ${result.dest}`);
+    }
+    if (incoming.length > 0) {
+        console.log(`\n${pc.yellow('충돌')} — 아래 파일은 이미 존재해 .harness/incoming/ 에 두었습니다:`);
+        for (const result of incoming) {
+            console.log(`  ${pc.yellow('~')} ${result.dest}`);
+            console.log(`    비교: diff ${result.dest} .harness/incoming/${result.dest}.incoming`);
+        }
+    }
+    const patch = patchEslintIgnores(detected, options.dryRun);
+    if (patch.status === 'patched') {
+        console.log(`\n${pc.green('패치')} — ${patch.file} 에 하네스 파일 ignores 를 추가했습니다:\n` +
+            pc.dim(patch.snippet));
+    }
+    else if (patch.status === 'unrecognized') {
+        console.log(`\n${pc.yellow('수동 필요')} — ${patch.file} 의 export 형태를 알아보지 못했습니다.\n` +
+            `  설정 배열 안에 아래를 직접 넣으세요 (없으면 eslint가 .harness/ 를 검사합니다):\n` +
+            pc.dim(patch.snippet));
+    }
+    if (hasStylelintBaseline(detected, options)) {
+        console.log(`\n${pc.yellow('stylelint 유예')} — 색상 원시값을 쓰던 기존 CSS ` +
+            `${detected.cssFilesWithRawColor.length}개를 .harness/stylelint-baseline.json 에 올렸습니다.\n` +
+            pc.dim('  이 파일들만 warning 이고 새로 만드는 CSS는 error 입니다.\n' +
+                '  정리할 때마다 목록에서 경로를 지우세요. 비면 stylelint.config.js 의 overrides 를 삭제하면 됩니다.'));
+    }
+    if (ponytailTag) {
+        console.log(`\n${pc.green('ponytail')} — Cursor 규칙을 릴리스 ${ponytailTag}에서 받아 설치했습니다 (.cursor/rules/ponytail.mdc).`);
+    }
+    else if (ponytailFetchFailed) {
+        console.log(`\n${pc.yellow('ponytail')} — 규칙 파일을 받아오지 못했습니다 (네트워크를 확인하세요).\n` +
+            pc.dim('  수동 설치: https://github.com/DietrichGebert/ponytail 의 .cursor/rules/ponytail.mdc 를 프로젝트에 복사하세요.'));
+    }
+    const deps = requiredDevDeps(options);
+    if (deps.length > 0) {
+        console.log(`\n선택한 모듈이 요구하는 의존성 (자동 설치하지 않습니다):\n  ${pc.cyan(`${detected.packageManager} install -D ${deps.join(' ')}`)}`);
+    }
+    const steps = [
+        'AGENTS.md 의 TODO와 docs/product-spec.md 를 프로젝트에 맞게 채우세요',
+        '.harness/config.json 의 checks 를 확인하세요 (게이트·/verify 가 이 목록을 실행합니다)',
+    ];
+    if (options.modules.includes('design-system')) {
+        steps.push('UI 작업 전이라면 /ds-init 워크플로로 Storybook을 설치하세요');
+    }
+    if (options.ponytail && options.agents.includes('claude')) {
+        steps.unshift('ponytail(Claude Code) 설치 — 아래 두 명령을 각각 별도 메시지로 보내세요:\n' +
+            '     /plugin marketplace add DietrichGebert/ponytail\n' +
+            '     /plugin install ponytail@ponytail');
+    }
+    console.log(`\n다음 단계:\n` +
+        steps.map((step, index) => `  ${index + 1}. ${step}`).join('\n'));
+    p.outro('done');
+};
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/dist/detect.js

@@ -0,0 +1,128 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+const detectPackageManager = (targetDir) => {
+    if (existsSync(path.join(targetDir, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (existsSync(path.join(targetDir, 'yarn.lock')))
+        return 'yarn';
+    if (existsSync(path.join(targetDir, 'bun.lock')))
+        return 'bun';
+    if (existsSync(path.join(targetDir, 'bun.lockb')))
+        return 'bun';
+    return 'npm';
+};
+const ESLINT_FLAT_CONFIG_CANDIDATES = [
+    'eslint.config.js',
+    'eslint.config.mjs',
+    'eslint.config.cjs',
+    'eslint.config.ts',
+    'eslint.config.mts',
+    'eslint.config.cts',
+];
+const CSS_IN_JS_PACKAGES = [
+    'styled-components',
+    '@emotion/styled',
+    '@emotion/react',
+    '@stitches/react',
+    '@vanilla-extract/css',
+];
+/** 선언부의 색상 원시값 — 토큰 강제를 곧바로 error로 켰을 때 걸릴 것들 */
+const RAW_COLOR_PATTERN = /(?:color|fill|stroke|background|border-color|outline-color)[^;{}]*:[^;{}]*(#[0-9a-fA-F]{3,8}\b|rgba?\(|hsla?\()/;
+/**
+ * src/ 안에서 색상 원시값을 쓰는 기존 CSS 파일을 찾는다.
+ * 기존 프로젝트에 토큰 강제를 error로 얹으면 첫 커밋부터 수백 건이 막혀
+ * 게이트를 꺼버리게 된다 — 이 목록이 stylelint 유예(baseline) 대상이 된다.
+ */
+const findCssFilesWithRawColor = (targetDir) => {
+    const srcDir = path.join(targetDir, 'src');
+    if (!existsSync(srcDir))
+        return [];
+    const found = [];
+    const MAX_FILES_SCANNED = 2000;
+    let scanned = 0;
+    const walk = (dir) => {
+        if (scanned >= MAX_FILES_SCANNED)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (scanned >= MAX_FILES_SCANNED)
+                return;
+            if (entry.name.startsWith('.') || entry.name === 'node_modules') {
+                continue;
+            }
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.name.endsWith('.css')) {
+                scanned += 1;
+                try {
+                    if (RAW_COLOR_PATTERN.test(readFileSync(full, 'utf-8'))) {
+                        found.push(path.relative(targetDir, full).split(path.sep).join('/'));
+                    }
+                }
+                catch {
+                    // 읽을 수 없는 파일은 없는 것으로 취급
+                }
+            }
+        }
+    };
+    walk(srcDir);
+    return found.sort();
+};
+const AGENT_FILE_CANDIDATES = [
+    'AGENTS.md',
+    'CLAUDE.md',
+    '.cursor/rules',
+    '.cursor/hooks.json',
+    '.claude/settings.json',
+    '.claude/skills',
+    '.harness',
+];
+export const detect = (targetDir) => {
+    const pkgPath = path.join(targetDir, 'package.json');
+    const hasPackageJson = existsSync(pkgPath);
+    let projectName = path.basename(path.resolve(targetDir));
+    let scripts = {};
+    let deps = {};
+    if (hasPackageJson) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+            if (pkg.name)
+                projectName = pkg.name;
+            scripts = pkg.scripts ?? {};
+            deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        }
+        catch {
+            // 깨진 package.json은 없는 것으로 취급
+        }
+    }
+    const existingAgentFiles = AGENT_FILE_CANDIDATES.filter((candidate) => existsSync(path.join(targetDir, candidate)));
+    return {
+        targetDir,
+        hasPackageJson,
+        projectName,
+        packageManager: detectPackageManager(targetDir),
+        isReact: 'react' in deps,
+        isVite: 'vite' in deps,
+        isTypeScript: 'typescript' in deps ||
+            existsSync(path.join(targetDir, 'tsconfig.json')),
+        hasAxios: 'axios' in deps,
+        hasReactRouter: 'react-router-dom' in deps || 'react-router' in deps,
+        hasTanstackQuery: '@tanstack/react-query' in deps || 'react-query' in deps,
+        hasZustand: 'zustand' in deps,
+        hasTailwind: 'tailwindcss' in deps,
+        hasCssInJs: CSS_IN_JS_PACKAGES.some((pkg) => pkg in deps),
+        hasEslintFlatConfig: ESLINT_FLAT_CONFIG_CANDIDATES.some((candidate) => existsSync(path.join(targetDir, candidate))),
+        eslintConfigFile: ESLINT_FLAT_CONFIG_CANDIDATES.find((candidate) => existsSync(path.join(targetDir, candidate))),
+        cssFilesWithRawColor: findCssFilesWithRawColor(targetDir),
+        scripts,
+        existingAgentFiles,
+    };
+};

package/dist/eslintPatch.js

@@ -0,0 +1,58 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * 하네스가 만드는 파일 중 호스트 eslint가 집어들면 안 되는 것들.
+ * `.harness/gates/*.mjs` 는 Node 인프라 스크립트이고,
+ * `.harness/incoming/**` 는 tsconfig 밖에 있어 타입 인식 린트가 파싱에 실패한다.
+ */
+const HARNESS_IGNORES = ['.harness/**'];
+const MARKER = 'create-harness';
+const SNIPPET_LINES = [
+    `    // ${MARKER}: 하네스 생성 파일은 호스트 lint 대상이 아니다`,
+    `    { ignores: [${HARNESS_IGNORES.map((glob) => `'${glob}'`).join(', ')}] },`,
+];
+/**
+ * flat config 배열의 여는 괄호를 찾는다.
+ * `export default [` · `export default tseslint.config(` · `export default defineConfig([`
+ * 세 가지가 실사용의 대부분이고, 어느 쪽이든 바로 뒤에 설정 객체를 끼워 넣을 수 있다.
+ */
+const findInsertionPoint = (source) => {
+    const match = /export\s+default\s+(?:[\w.]+\s*\(\s*)?\[?/.exec(source);
+    if (!match)
+        return null;
+    const tail = match[0].trimEnd();
+    // 배열 리터럴이나 함수 호출이 열린 지점 바로 뒤여야 한다
+    if (!/[[(]$/.test(tail))
+        return null;
+    return match.index + match[0].length;
+};
+/**
+ * 호스트의 eslint flat config에 `.harness/**` ignores를 끼워 넣는다.
+ *
+ * 사용자 파일을 고치는 일이라 보수적으로 간다 — 알아볼 수 있는 형태에만 손대고,
+ * 이미 적용돼 있으면 아무것도 하지 않으며(멱등), 실패하면 조각만 돌려주고 물러난다.
+ */
+export const patchEslintIgnores = (detected, dryRun) => {
+    const snippet = SNIPPET_LINES.join('\n');
+    const file = detected.eslintConfigFile;
+    if (!file)
+        return { status: 'no-config', snippet };
+    const absPath = path.join(detected.targetDir, file);
+    let source;
+    try {
+        source = readFileSync(absPath, 'utf-8');
+    }
+    catch {
+        return { status: 'no-config', snippet };
+    }
+    if (source.includes(MARKER) || /['"`]\.harness\/\*\*['"`]/.test(source)) {
+        return { status: 'already-present', file, snippet };
+    }
+    const insertAt = findInsertionPoint(source);
+    if (insertAt === null)
+        return { status: 'unrecognized', file, snippet };
+    const patched = `${source.slice(0, insertAt)}\n${snippet}${source.slice(insertAt)}`;
+    if (!dryRun)
+        writeFileSync(absPath, patched, 'utf-8');
+    return { status: 'patched', file, snippet };
+};

package/dist/manifest.js

@@ -0,0 +1,63 @@
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+export const sha256 = (content) => createHash('sha256').update(content, 'utf-8').digest('hex');
+/**
+ * 파일을 쓴다. 대상 경로에 내용이 다른 파일이 이미 있으면 덮어쓰지 않고
+ * .harness/incoming/ 아래 같은 상대 경로에 두어 사용자가 비교할 수 있게 한다.
+ */
+export const writeActions = (actions, targetDir, dryRun) => actions.map((action) => {
+    const absDest = path.join(targetDir, action.dest);
+    let placedInIncoming = false;
+    if (existsSync(absDest)) {
+        const existing = readFileSync(absDest, 'utf-8');
+        if (existing === action.content) {
+            // 동일 내용이면 그대로 둔다 (재실행 멱등성)
+            return {
+                dest: action.dest,
+                placedInIncoming: false,
+                sha256: sha256(action.content),
+                module: action.module,
+            };
+        }
+        placedInIncoming = true;
+    }
+    // .incoming 접미사: 대상 프로젝트의 tsc·eslint가 이 파일을 집어들지 않게 한다
+    const finalPath = placedInIncoming
+        ? path.join(targetDir, '.harness/incoming', `${action.dest}.incoming`)
+        : absDest;
+    if (!dryRun) {
+        mkdirSync(path.dirname(finalPath), { recursive: true });
+        writeFileSync(finalPath, action.content, 'utf-8');
+        if (action.executable)
+            chmodSync(finalPath, 0o755);
+    }
+    return {
+        dest: action.dest,
+        placedInIncoming,
+        sha256: sha256(action.content),
+        module: action.module,
+    };
+});
+export const writeManifest = (results, options, version, dryRun) => {
+    const manifest = {
+        version,
+        createdAt: new Date().toISOString(),
+        preset: options.preset,
+        agents: options.agents,
+        modules: options.modules,
+        files: results
+            .filter((result) => !result.placedInIncoming)
+            .map((result) => ({
+            path: result.dest,
+            sha256: result.sha256,
+            module: result.module,
+        })),
+    };
+    if (!dryRun) {
+        const manifestPath = path.join(options.targetDir, '.harness/manifest.json');
+        mkdirSync(path.dirname(manifestPath), { recursive: true });
+        writeFileSync(manifestPath, JSON.stringify(manifest, null, 4) + '\n', 'utf-8');
+    }
+    return manifest;
+};

package/dist/ponytail.js

@@ -0,0 +1,56 @@
+const REPO = 'DietrichGebert/ponytail';
+const RULE_PATH = '.cursor/rules/ponytail.mdc';
+const FETCH_TIMEOUT_MS = 5000;
+const withTimeout = async (fetchImpl, url, init) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        return await fetchImpl(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+/**
+ * GitHub Releases API로 최신 릴리스 태그를 찾는다.
+ * main 브랜치를 그대로 받으면 재실행마다 결과가 달라져 이 CLI가 지키는
+ * 멱등성 원칙과 어긋난다 — 태그에 고정해 같은 버전을 반복 재현한다.
+ */
+export const fetchLatestPonytailTag = async (fetchImpl = fetch) => {
+    const res = await withTimeout(fetchImpl, `https://api.github.com/repos/${REPO}/releases/latest`, { headers: { Accept: 'application/vnd.github+json' } });
+    if (!res.ok)
+        throw new Error(`GitHub API ${res.status}`);
+    const body = (await res.json());
+    if (!body.tag_name)
+        throw new Error('tag_name 없음');
+    return body.tag_name;
+};
+/** 고정된 릴리스 태그에서 Cursor 규칙 파일 원문을 받는다 (벤더링이 아니라 실행 시점 fetch) */
+export const fetchPonytailCursorRule = async (tag, fetchImpl = fetch) => {
+    const res = await withTimeout(fetchImpl, `https://raw.githubusercontent.com/${REPO}/${tag}/${RULE_PATH}`);
+    if (!res.ok)
+        throw new Error(`raw.githubusercontent.com ${res.status}`);
+    return res.text();
+};
+/**
+ * ponytail의 Cursor 규칙 파일을 최신 릴리스에서 받아 IFileAction으로 돌려준다.
+ * 네트워크·API 실패는 여기서 흡수하고 null을 돌려준다 — 호출부는 실패해도
+ * 스캐폴딩 전체를 막지 않고 수동 설치 안내로 폴백해야 하기 때문이다.
+ */
+export const buildPonytailAction = async (fetchImpl = fetch) => {
+    try {
+        const tag = await fetchLatestPonytailTag(fetchImpl);
+        const content = await fetchPonytailCursorRule(tag, fetchImpl);
+        return {
+            tag,
+            action: {
+                dest: RULE_PATH,
+                content,
+                module: 'ponytail',
+            },
+        };
+    }
+    catch {
+        return null;
+    }
+};