vibecoding-collector

바이브코딩대학 "수강생 프롬프트 수집"의 수강생 온보딩 CLI입니다. 수강생이 한 줄 명령으로 본인 확인 → 개인 키 발급 → 코스 폴더에 수집 hook 설치까지 마치도록 합니다. (Phase2 — 개인키 인증판)

사용법

npx vibecoding-collector init

패키지는 npm 에 게시되어 있어 위 명령으로 바로 실행됩니다. 로컬 개발 시에는 다음으로 실행합니다.

# 패키지 폴더에서 직접
node bin/init.js init
# 또는 npx 로컬 경로
npx . init        # (cli/ 폴더 안에서)
# 또는 npm pack 으로 만든 tarball 설치 후 실행

대화 흐름

init 은 다음을 순서대로 진행합니다.

0. 버전 게이트(자기-차단) — PIPA 고지보다 먼저, npm 레지스트리에서 최신 버전을 조회합니다.
   • 설치본이 구버전이면 아무것도 설치하지 않고 중단하며, 다음 안내를 출력합니다(종료코드 1).

     최신 버전 X.Y.Z가 있습니다. 'npx vibecoding-collector@latest init' 로 다시 실행해 주세요.

     → 반드시 npx vibecoding-collector@latest init 로 다시 실행해 주세요. (npx 캐시에 구버전이 남아 있어도 @latest 를 붙이면 최신 버전을 내려받아 실행합니다.)
   • 조회에 실패하면(네트워크 오류·타임아웃 등) 버전 확인을 건너뜁니다 경고만 출력하고 정상 진행(fail-open).
   • 최신이거나 더 높은 버전이면 조용히 다음 단계로 넘어갑니다.
1. 개인정보 수집·이용 동의 고지(PIPA) 출력 후 y/N 동의.
   • 동의하지 않으면 아무것도 설치하지 않고 즉시 중단합니다(수강에는 영향 없음).
2. 이메일 입력 (본인 확인용 — 수강 신청에 사용한 이메일). @ 포함 여부만 클라이언트에서 확인하고, 정규화·매칭은 서버가 담당합니다.
3. 코스 폴더 경로 입력 (기본값: 현재 디렉터리).
4. 서버에 본인 확인 요청:

   POST {BASE_URL}/enroll/verify   { email, consent: true }

   • 확인 성공(200) → 개인 키를 받고 ○○님(과정) 확인됨 출력 후 설치. (이름·과정은 서버가 매칭해 응답한 student.name·student.course를 그대로 표시합니다.)
   • 확인 실패(비200/오류) → "등록된 수강생 정보를 찾지 못했습니다" 안내 후 중단. (보안상 실패의 상세 사유는 화면에 노출하지 않습니다.)

수집 서버 주소(BASE_URL)는 수강생에게 묻지 않습니다. 패키지에 내장되어 있어 수강생은 서버 주소를 알 필요가 없습니다. 결정된 값은 .env 의 BASE_URL 에만 기록됩니다.

버전 게이트 (자기-차단)

init 은 시작 직후 npm 레지스트리에서 최신 버전을 조회해, 구버전 설치본이면 설치를 진행하지 않고 차단합니다("차단 후 업데이트 요구"). 학생이 npx 캐시에 박힌 옛 버전을 계속 실행하는 것을 막기 위함입니다.

| 항목 | 값 | |---|---| | 레지스트리 조회 | GET https://registry.npmjs.org/vibecoding-collector/latest (응답 JSON 의 .version 이 최신 버전) | | 현재 버전 | package.json 의 version | | semver 비교 | major.minor.patch 세 숫자만 비교. -rc1 등 pre-release 꼬리표는 무시(앞 3자리만) | | 구버전(current < latest) | 차단 — 안내 출력 후 설치 없이 종료(코드 1) | | 조회 실패(네트워크·타임아웃·비200·JSON 파싱불가·404) | fail-open — 버전 확인을 건너뜁니다 경고 후 정상 진행 | | 동일/상위 버전 | 조용히 진행 |

• 구현: lib/version-check.js 의 checkForUpdate({ timeoutMs, registryUrl }). Node 내장 https/http 만 사용(외부 의존 0)하며 절대 throw 하지 않습니다(어떤 오류도 checkFailed 로 흡수).
• 게이트는 init 서브커맨드에만 적용됩니다. --help 등 다른 흐름은 영향받지 않습니다.
• 차단 시 안내: 최신 버전 X.Y.Z가 있습니다. 'npx vibecoding-collector@latest init' 로 다시 실행해 주세요.

BASE_URL 결정 우선순위 (운영자·개발용)

대화형 질문 대신 다음 우선순위로 수집 서버 주소를 정합니다.

1. VCU_BASE_URL 환경변수 — dev/테스트 override.

   VCU_BASE_URL=http://127.0.0.1:8077 npx vibecoding-collector init

2. --base-url <url> 플래그 — (있으면)

   npx vibecoding-collector init --base-url https://collect.example.com
   # --base-url=<url> 형태도 지원

3. 내장 상수 DEFAULT_BASE_URL — 기본값. 운영 backend(Railway 배포본) https://backend-production-986a.up.railway.app 로 내장되어 있어, 별도 override 없이 npx vibecoding-collector init 만 실행하면 운영 서버로 본인확인됩니다. bin/init.js 의 DEFAULT_BASE_URL 상수입니다.

설치되는 파일

코스 폴더(<courseDir>) 아래에 다음이 생성/갱신됩니다.

| 경로 | 내용 | |---|---| | .claude/settings.json | Claude Code hook 6개 등록(prompt·posttooluse·stop·subagentstop·sessionstart·sessionend → node collect.js <phase>) | | .claude/hooks/collect.js | 프롬프트/도구/transcript 수집 클라이언트 (STUDENT_KEY 인증판, 비차단·store-and-forward 큐·서브에이전트 캡처 포함) | | .claude/.env | STUDENT_KEY(발급 키), BASE_URL. 권한 0600. 커밋 금지 | | .gitignore | .env·queue/·spool/·collect-errors.log 무시 항목 병합(중복 없이 append) |

기존 파일이 있으면 덮어쓰기 전에 *.bak-<타임스탬프> 로 백업합니다.

인증 방식 (Phase1 → Phase2 차이)

번들된 collect.js 는 Phase1 검증본을 베이스로 하며 인증만 달라집니다.

• Phase1: .env 의 STUDENT_ID(요청 body) + INGEST_TOKEN(Bearer)을 함께 전송.
• Phase2 (이 패키지): .env 의 STUDENT_KEY 한 개만 사용.
  • 모든 ingest 요청에 Authorization: Bearer <STUDENT_KEY> 헤더로 전송.
  • 서버가 키로 수강생(user_id)을 해석하므로 클라이언트는 student_id 를 보내지 않습니다 (이벤트 body 의 student_id 및 transcript 의 X-Student-Id 헤더 제거).
  • 비차단 detach 전송, 디스크 큐, spool, subagent 캡처, wait_for_flush 등 나머지 수집 로직은 Phase1 검증본과 100% 동일합니다.

서버 계약 (p2-backend 공유)

POST /enroll/verify
  body: { "email": "...", "consent": true }
  200 : { "ok": true, "key": "<STUDENT_KEY>", "student": { "name": "...", "course": "..." } }
  비200: 본인확인 실패

# 설치된 collect.js → ingest
POST /api/events      Authorization: Bearer <STUDENT_KEY>
POST /api/transcript  Authorization: Bearer <STUDENT_KEY>

패키지 구조

cli/
├── bin/init.js          # 엔트리포인트(대화 흐름·출력만)
├── lib/
│   ├── pipa.js          # PIPA 동의 고지문
│   ├── prompt.js        # readline 입력 헬퍼(내장 모듈만)
│   ├── verify.js        # POST /enroll/verify 클라이언트
│   ├── version-check.js # 버전 게이트(레지스트리 latest 조회·semver 비교, fail-open)
│   └── install.js       # 코스 폴더 설치 로직
├── templates/
│   ├── settings.json    # hook 6개(코스 폴더로 복사)
│   ├── gitignore        # .gitignore 병합 소스
│   └── hooks/collect.js # STUDENT_KEY 인증판 수집 클라이언트
├── test/run.js          # 자체 검증(스텁 입력·임시 폴더 설치·미동의 중단·미스매치)
└── package.json

자체 검증

외부 의존 없이 Node 내장 모듈로 동작합니다.

node test/run.js

테스트는 stub 입력(동의·이메일·코스폴더 3줄 — BASE_URL 은 더 이상 묻지 않음)으로 runInit 을 구동해 ① 동의 후 본인확인 성공 시 임시 코스 폴더에 3종(.claude/settings.json·hooks/collect.js·.env) + .gitignore 생성 및 .env 에 키 기록

• verify body 가 {email, consent} 형태(name/phone 미전송) + 대화형 BASE_URL 질문 미출력, ② 미동의 시 중단(미설치), ③ 서버 미스매치(비200) 시 미설치, ④ 번들 collect.js 의 node --check 통과, ⑤ resolveBaseUrl 우선순위(VCU_BASE_URL > --base-url 플래그 > 내장 DEFAULT_BASE_URL), ⑥ VCU_BASE_URL override 가 대화형 질문 없이 그 주소로 verify 요청을 보내고 .env 의 BASE_URL 에 기록되는지, ⑦ semver 비교(parseSemver/compareSemver — 같음/높음/낮음/파싱불가), ⑧ 버전 게이트(mock 레지스트리: (a) 상위 버전이면 차단·미설치·종료코드 1, (b) 동일 버전이면 진행·설치, (c) 서버 다운/(d) 404 이면 fail-open 진행)를 확인합니다.