@kaydash9999/banker-plugins 0.7.1 → 0.9.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude Code skills + commands — QA, audit, docs, architecture, dependency setup, and wiki; the banker plugin marketplace.",
-    "version": "0.7.1"
+    "version": "0.9.0"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "banker",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Claude Code plugin: QA/audit/docs/architecture skills + commands, a /banker:setup installer for OS dependencies (playwright, etc.), and wiki compaction.",
   "author": {
     "name": "smallOpenSource",

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [0.9.0] - 2026-07-18
+
+### Added
+- **개인화 업데이트 알림**: 새 버전이 나왔을 때, 그 버전에서 바뀐 스킬 중 이 설치에서 실제로 써 본 스킬이 있으면 알림에 그 스킬 이름을 넣어 보여준다("자주 쓰는 스킬이 이번 업데이트에서 바뀌었습니다: ..."). 교집합이 없으면 기존 일반 알림으로 폴백한다.
+  - **로컬 "써 본 스킬" 집합**: 카운팅 훅(PostToolUse Skill / UserPromptExpansion)이 스킬 이름을 config 폴더의 `used-skills.json` 에 union 으로 모은다. 이 집합은 절대 전송하지 않는다 — 체크인 페이로드는 여전히 `{version, os, counts}` 뿐이다. 상한(300)·중복 무기록·원자적 기록.
+  - **바뀐 스킬 목록(공개 GitHub raw)**: 버전별 바뀐 스킬을 담은 `skill-changes.json` 을 저장소에서 GET 으로 조회한다(카운팅 활성 경로의 update-checkin 이 best-effort; 개인화 표시가 카운팅에 게이트되므로 카운팅 opt-out 경로의 update-fetch 는 조회하지 않는다). 무페이로드 GET 이라 식별자 전송이 없고, 실패하면 일반 알림으로 폴백한다. 릴리스마다 `scripts/gen-skill-changes.js`(git diff 기반·배포 제외)로 채운다.
+  - 두 opt-out(`BANKER_NO_UPDATE_CHECK`·`BANKER_NO_TELEMETRY`) 중 어느 쪽을 켜도 개인화는 동작하지 않는다. Codex CLI는 네트워크 차단으로 배제된다.
+  - `PRIVACY.md` 에 개인화 항목을 추가했다(로컬 집합 미전송·매니페스트 GET 수신자=GitHub).
+
+### Fixed
+- `PRIVACY.md`·CHANGELOG 의 "0.8.0 아직 게시 안 됨" 상태 문구를 실제(게시됨)에 맞게 정정했다. EU ePrivacy opt-in 전환 여부는 열린 검토 항목으로 표기를 유지한다.
+
+## [0.8.0] - 2026-07-17
+
+### Added
+- README 에 npm 월간 다운로드 배지와 GitHub stars 배지를 추가했다.
+- `banker setup` 최초 실행 시 GitHub 저장소 별(star)을 요청하는 프롬프트를 추가했다(양 런타임 공통·홍보 목적·카운팅 opt-out 여부와 무관).
+- **업데이트-체크 서비스**: 이전 초안(opt-in 익명 텔레메트리 클라이언트, 기본값 미수집)은 동의자가 거의 없어 사용량 가시성이라는 목표를 달성하지 못한다고 판단해 두 기능으로 재구성(피벗)했다.
+  - **업데이트 알림**: 공개 npm 레지스트리(`registry.npmjs.org/@kaydash9999/banker-plugins/latest`)를 조회해 세션 시작 시 새 버전이 있으면 알린다. 조회 요청의 수신자는 npm(GitHub/Microsoft)이고, banker 유지보수자는 이 조회를 받지 않는다. 기본값 켜짐, `BANKER_NO_UPDATE_CHECK` 환경변수 또는 `config.updateCheck=false` 로 끌 수 있다.
+  - **사용량 카운팅(count-default-on)**: 하루 1회 스킬/커맨드별 호출 수를 시간대(hour-of-day)별로 버킷화해 플러그인 버전·OS 종류와 함께 유지보수자가 운영하는 외부 엔드포인트로 익명 체크인한다. 집계는 사용자가 직접 입력한 `/banker:*` 커맨드와 모델이 자동 호출한 스킬 양쪽을 서로 다른 두 훅으로 겹침 없이 포착한다. 기본값 켜짐, `BANKER_NO_TELEMETRY` 환경변수·`config.telemetry=false`·`banker telemetry off` 로 끌 수 있다.
+  - **기본 카운팅 엔드포인트 내장**: 배포에 기본 엔드포인트(`banker.banker-plugins.workers.dev`, 유지보수자의 Cloudflare Worker)를 박아 `endpoint()` 가 env·config 미설정이어도 이를 반환한다. 그 결과 `countingActive()` 가 실제로 default-on 이 되어 opt-out 하지 않은 모든 설치에서 카운팅이 활성이다(이전엔 엔드포인트 미설정이라 사실상 유지보수자 셸만 잡혔다). 자가호스팅/override 는 `BANKER_TELEMETRY_ENDPOINT` 환경변수로 한다.
+  - 두 기능 모두 Claude Code 전용이다. Codex CLI는 샌드박스가 네트워크 접근을 차단하므로 알림·카운팅 둘 다 배제된다.
+  - `PRIVACY.md` 를 이 설계에 맞게 재작성했다: 알림/카운팅을 분리 기술하고 각각의 수신자를 이름으로 명시했다(알림=npm, 카운팅=유지보수자). 익명성이 페이로드의 속성이지 시스템 전체의 속성은 아니라는 점(카운팅 서버는 소스 IP를 수신하되 기록하지 않도록 설계)을 정직하게 밝혔다. EU ePrivacy Art.5(3)·Planet49 판례는 표준 관행 근거와 반대 근거를 양면으로 제시했고, 미국 CCPA·한국 PIPA는 이 익명 체크인에 재적용하지 않는다는 점(실무 판단 기준인 IP 지속 보유·프로파일링·판매에 해당하지 않음)을 명기했다.
+
+### Notes
+- **정직 명시**: 이 릴리스는 npm·GitHub·마켓플레이스에 게시되었다. 초안 당시 계획했던 "EU ePrivacy opt-in 전환 검토 통과 후 게시" 게이트는 게시 결정으로 우회되었고, EU ePrivacy opt-in 전환 여부는 `PRIVACY.md` 의 열린 검토 항목으로 남아 있다.
+
 ## [0.7.1] - 2026-07-16
 
 ### Changed

package/PRIVACY.md

@@ -0,0 +1,106 @@
+# 프라이버시 고지
+
+> banker 플러그인의 업데이트-체크 서비스(업데이트 알림 + 익명 사용량 카운팅)에 대한 프라이버시 고지입니다.
+
+## 개요
+
+이 문서는 두 개의 독립된 기능을 설명합니다.\
+하나는 새 버전이 나왔을 때 알려주는 **업데이트 알림**이고, 다른 하나는 유지보수자가 사용량을 파악하기 위한 **익명 사용량 카운팅**입니다.\
+두 기능 모두 기본값은 켜짐(default-on)이며, 각각 독립적으로 끌 수 있습니다.\
+이 기능은 Claude Code 런타임에서만 동작합니다. Codex CLI는 샌드박스가 네트워크 접근을 차단하므로 알림과 카운팅 둘 다 동작하지 않습니다.
+
+## 현재 상태
+
+이 문서가 기술하는 업데이트-체크 서비스(업데이트 알림 + 익명 사용량 카운팅 + 개인화)는 게시된 버전에 포함되어 동작합니다.\
+각 버전의 실제 게시 여부는 npm 레지스트리(`@kaydash9999/banker-plugins`)가 정본입니다. 아래 "법적 상태"에서 다루는 EU ePrivacy opt-in 검토는 여전히 열린 항목이며, 현재 배포 방침은 사전 고지 + opt-out 입니다.\
+이 문구는 추가 검토 결과에 따라 더 정교해질 수 있습니다.
+
+## 업데이트 알림
+
+공개 npm 레지스트리(`https://registry.npmjs.org/@kaydash9999/banker-plugins/latest`)에서 최신 버전을 조회하고, 설치된 버전보다 최신 버전이 있으면 세션 시작 시 알립니다.\
+이 조회 요청의 수신자는 **npm(GitHub/Microsoft가 운영)**입니다. banker 유지보수자는 이 조회를 전혀 수신하지 않습니다.\
+update-notifier·Homebrew 등 다른 CLI 도구가 쓰는 것과 같은 방식입니다.
+
+기본값은 켜짐입니다.\
+환경변수 `BANKER_NO_UPDATE_CHECK` 를 설정하거나 config의 `updateCheck` 를 `false` 로 두면 끌 수 있습니다.
+
+### 개인화 (선택적 강화)
+
+새 버전이 있을 때, 그 버전에서 바뀐 스킬 중 이 설치에서 실제로 써 본 스킬이 있으면 알림에 그 스킬 이름을 넣어 보여줍니다("자주 쓰는 스킬이 이번 업데이트에서 바뀌었습니다: ...").\
+이를 위해 두 가지가 쓰이며, 어느 것도 새로운 개인식별정보를 서버로 보내지 않습니다.
+
+- **로컬 "써 본 스킬" 집합**: 이 기기의 config 폴더에 `used-skills.json` 로 스킬 이름만 모아 둡니다. 이 파일은 **절대 전송하지 않습니다**. 사용량 카운팅 체크인의 페이로드는 여전히 `{version, os, counts}` 세 키뿐이며 이 집합을 포함하지 않습니다. 오직 세션 시작 시 로컬에서 읽어 알림 문구를 개인화하는 데만 씁니다.
+- **바뀐 스킬 목록 조회**: 어떤 스킬이 바뀌었는지는 공개 GitHub raw(저장소의 `skill-changes.json`)에서 GET 으로 조회합니다. 이 요청의 수신자는 **GitHub(Microsoft가 운영)**이고, GET 이라 페이로드나 식별자를 보내지 않습니다. 업데이트 버전 조회(npm)와 같은 성격의 무페이로드 조회입니다.
+
+개인화는 두 opt-out 중 어느 쪽으로도 완전히 꺼집니다.\
+`BANKER_NO_UPDATE_CHECK`(또는 config `updateCheck=false`)는 업데이트 알림 자체를 끄므로 개인화도 함께 사라집니다.\
+`BANKER_NO_TELEMETRY`(또는 config `telemetry=false`·`banker telemetry off`)는 개인화가 기반하는 사용량 카운팅을 끄므로, 로컬 "써 본 스킬" 집합의 **기록**과 알림에서의 **표시**가 모두 중단됩니다(이미 쌓인 로컬 집합이 있어도 표시하지 않으며, 이 경우 일반 업데이트 알림은 계속 표시됩니다).
+
+## 사용량 카운팅
+
+하루 1회, 유지보수자가 운영하는 외부 엔드포인트(banker 패키지 밖에서 별도로 운영되는 serverless)로 익명 체크인을 전송합니다.\
+플러그인은 기본 카운팅 엔드포인트(`banker.banker-plugins.workers.dev`)를 내장하므로, count-default-on 이라 설치 즉시 활성입니다.\
+`BANKER_TELEMETRY_ENDPOINT` 환경변수로 자가호스팅 엔드포인트를 지정하거나 override 할 수 있습니다.
+
+### 수집 항목
+
+- 스킬/커맨드별 호출 횟수를 시간대(hour-of-day, 0시~23시)별로 버킷화한 값
+- 플러그인 버전
+- OS 종류(linux/darwin/win32 수준)
+
+개별 호출의 시각은 전송하지 않고 시간대 버킷까지만 뭉쳐서 보냅니다.\
+집계 대상은 사용자가 직접 입력한 `/banker:*` 커맨드와 모델이 자동으로 호출한 스킬 양쪽 모두이며, 서로 다른 두 훅이 겹치지 않게 나누어 포착합니다.
+
+### 수집하지 않는 항목
+
+- 이름, 이메일 등 개인식별정보(PII)
+- 코드 및 파일 내용, 커맨드 인자
+- 저장소·계정 정보
+- 지속적인 사용자 또는 기기 식별자(UUID·머신ID 등을 생성하지 않습니다)
+- 페이로드 안의 IP 주소
+
+기본값은 켜짐(count-default-on)입니다.\
+환경변수 `BANKER_NO_TELEMETRY` 를 설정하거나, config의 `telemetry` 를 `false` 로 두거나, `banker telemetry off` 를 실행하면 끌 수 있습니다.\
+`banker setup` 첫 실행 시 이 기본값과 끄는 방법을 투명하게 고지합니다. 진행을 막는 opt-in 동의 프롬프트가 아니라 정보 제공입니다.
+
+## 익명성에 대한 정직한 고지
+
+익명성은 전송되는 데이터, 즉 페이로드 자체의 속성이지 시스템 전체의 속성이 아닙니다.\
+카운팅 엔드포인트는 네트워크 요청의 시스템 경계에서 TCP 소스 IP 주소를 봅니다. IP 주소는 GDPR과 한국 개인정보보호법(PIPA) 모두에서 개인정보로 취급됩니다.\
+이 엔드포인트는 banker 유지보수자가 운영하며, 수신 IP를 기록하지 않도록 설계되어 있습니다. banker 플러그인(클라이언트)과 카운팅 서버는 같은 운영자가 관리합니다.\
+반면 업데이트 알림 조회의 IP는 npm만 보며, banker 유지보수자는 어느 경로로도 보지 않습니다.\
+클라이언트인 banker가 보장하는 범위는 페이로드 안에 IP나 그 밖의 식별자를 넣지 않는다는 것까지이며, 서버가 수신 IP를 기록하지 않는 것은 서버를 운영하는 유지보수자의 설계 책임입니다.
+
+## 상시 훅 비용
+
+알림과 카운팅이 기본값으로 켜져 있기 때문에 다음 훅이 banker 활성화 중 항상 등록되어 있습니다.
+
+- `SessionStart`: 세션 시작 시 1회, 캐시된 업데이트 알림을 확인합니다(이 훅 자체는 네트워크 요청을 하지 않습니다).
+- `PostToolUse`(Skill 매처): 모델이 자동으로 호출한 스킬을 집계하고, 개인화용 로컬 "써 본 스킬" 집합을 갱신합니다(집계는 전송, 로컬 집합은 미전송).
+- `UserPromptExpansion`: 사용자가 직접 입력한 `/banker:*` 커맨드를 집계하고, 개인화용 로컬 "써 본 스킬" 집합을 갱신합니다.
+
+세 훅 모두 트리거될 때마다 짧게 실행되는 node 프로세스를 하나씩 기동합니다(수십 ms 수준).\
+opt-out 하더라도 훅의 등록 자체는 남고, 각 스크립트 내부의 게이트가 즉시 무동작으로 반환합니다.
+
+## 전송 안전
+
+- 업데이트 알림 조회는 GET 요청이며 페이로드가 없습니다.
+- 카운팅 체크인은 HTTPS만 사용합니다. 평문 http는 로컬 테스트용 loopback(localhost/127.0.0.1/::1) 엔드포인트에만 허용되고, 그 외 엔드포인트에는 거부됩니다.
+- 네트워크 조회·전송은 세션을 막지 않도록 분리 실행되며, 포그라운드 훅은 캐시 읽기만 하고 즉시 반환합니다.
+- 어떤 네트워크 오류도 삼키며(fail-closed), 항상 정상 종료합니다.
+
+## 법적 상태
+
+**EU ePrivacy는 양면을 그대로 남깁니다.**
+
+표준 관행이라는 근거: 익명 체크인, 요청 카운트, IP 미보유, 사전 고지와 opt-out의 조합은 사실상 업계 표준 관행에 해당합니다. 지속 식별자나 사용자별 프로파일을 만들지 않는 무상태 체크인이라는 점이 이 판단의 근거입니다.
+
+반대 근거: EU ePrivacy Directive Art.5(3)은 개인식별정보 여부와 무관하게 단말기(device) 접근 자체에 이용자 동의를 요구할 수 있습니다. Planet49 판례에 따르면 분석 목적의 opt-out은 유효한 동의로 인정되지 않을 수 있습니다. 즉 무상태 체크인이라도 접근 자체가 EU에서는 동의를 유발할 가능성이 있습니다.
+
+실무 결론: 실제로 EU 사용자를 대상으로 배포하기 전에는 opt-in 전환 여부를 별도로 검토해야 합니다. 현재 배포는 사전 고지 + opt-out 방식으로 운영되고 있으며, 이 EU ePrivacy opt-in 전환 여부는 열린 검토 항목으로 남아 있습니다.
+
+**미국 CCPA·한국 PIPA는 이 익명 업데이트-체크에 재적용하지 않습니다.** 두 법의 실무 판단 기준은 IP 주소의 지속적 보유, 사용자별 프로파일 구축, 데이터 판매 여부입니다.\
+이 기능의 익명 체크인은 이 중 어느 것도 하지 않습니다. IP를 기록하지 않고, 지속 식별자가 없고, 데이터를 판매하지 않습니다.\
+따라서 CCPA·PIPA를 이 기능의 별도 미해결 법적 쟁점으로 표기하지 않습니다. 위에서 다룬 EU ePrivacy는 이와 무관한 별건입니다.
+
+이 문구는 향후 더 정교해질 수 있습니다.

package/README.md

@@ -4,8 +4,9 @@
 
 [![npm](https://img.shields.io/npm/v/@kaydash9999/banker-plugins)](https://www.npmjs.com/package/@kaydash9999/banker-plugins)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![npm downloads](https://img.shields.io/npm/dm/@kaydash9999/banker-plugins)](https://www.npmjs.com/package/@kaydash9999/banker-plugins) [![GitHub stars](https://img.shields.io/github/stars/smallOpenSource/banker_plugins)](https://github.com/smallOpenSource/banker_plugins)
 
-[빠른 시작](#빠른-시작) · [구성](#구성) · [설치 상세](#설치-상세-npm--codex) · [요구사항](#요구사항) · [업데이트 / 제거](#업데이트--제거) · [라이선스 / 서드파티](#라이선스--서드파티)
+[빠른 시작](#빠른-시작) · [구성](#구성) · [설치 상세](#설치-상세-npm--codex) · [요구사항](#요구사항) · [업데이트 / 제거](#업데이트--제거) · [업데이트 확인](#업데이트-확인-및-사용량-카운팅) · [라이선스 / 서드파티](#라이선스--서드파티)
 
 banker는 QA·보안 감사·문서·아키텍처·위키 작업과 의존성·개발환경(OS별) 설치를 아우르는 **스킬 48개 + 커맨드 2개**(총 50개 구성요소)를 묶은 Claude Code 플러그인입니다.\
 설치하면 스킬과 커맨드가 `/banker:<이름>` 네임스페이스로 노출됩니다.\
@@ -174,6 +175,30 @@ banker uninstall                        # 제거
 
 Codex는 재설치할 때마다 기존 `banker-*` 를 먼저 정리하므로 옛 버전이 중복으로 남지 않습니다.
 
+## 업데이트 확인 및 사용량 카운팅
+
+banker는 기본값(default-on)으로 두 가지를 합니다.\
+새 버전이 나오면 세션 시작 시 알려주는 **업데이트 알림**과, 유지보수자가 사용량을 파악하는 **익명 사용량 카운팅**입니다.\
+이 때문에 `SessionStart`(알림 확인)·`PostToolUse`(모델이 자동 호출한 스킬 집계)·`UserPromptExpansion`(사용자가 직접 입력한 `/banker:*` 집계) 훅이 항상 등록되어 있고, 트리거될 때마다 짧게 node 프로세스를 하나씩 띄웁니다(수십 ms 수준).
+
+업데이트 알림은 **개인화**됩니다.\
+새 버전에서 바뀐 스킬 중 당신이 실제로 써 본 스킬이 있으면 그 이름을 알림에 넣어 보여줍니다("자주 쓰는 스킬이 이번 업데이트에서 바뀌었습니다: ...").\
+이를 위해 써 본 스킬 이름만 로컬 파일(`used-skills.json`)에 모으며, 이 목록은 전송하지 않습니다(바뀐 스킬 목록만 공개 GitHub raw 에서 무페이로드 GET 으로 조회).\
+개인화는 아래 두 opt-out 중 어느 쪽으로도 함께 꺼집니다.
+
+끄기:
+
+```bash
+export BANKER_NO_UPDATE_CHECK=1   # 업데이트 알림만 끄기
+export BANKER_NO_TELEMETRY=1      # 사용량 카운팅만 끄기
+```
+
+카운팅은 `banker telemetry off` 로도 끌 수 있습니다.\
+플러그인은 기본 카운팅 엔드포인트(`banker.banker-plugins.workers.dev`)를 내장하므로 count-default-on 이라 설치 즉시 활성이며, `BANKER_TELEMETRY_ENDPOINT` 환경변수로 자가호스팅/override 할 수 있습니다.\
+Codex CLI는 샌드박스가 네트워크를 차단하므로 알림·카운팅 둘 다 동작하지 않습니다.
+
+무엇을 수집하고 누가 수신하는지는 [PRIVACY.md](PRIVACY.md)에 정리했습니다.
+
 ## 라이선스 / 서드파티
 
 banker 자체는 **MIT** ([LICENSE](LICENSE)). Owner: [smallOpenSource](https://github.com/smallOpenSource).

package/bin/banker.js

@@ -11,12 +11,14 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const cp = require('child_process');
+const { pathToFileURL } = require('url');
 
 const PKG_ROOT = path.resolve(__dirname, '..');
 const MANIFEST = path.join(PKG_ROOT, 'codex', 'manifest.json');
 const PLUGIN_JSON = path.join(PKG_ROOT, '.claude-plugin', 'plugin.json');
 const MARKETPLACE = 'banker-plugins';
 const PLUGIN_NAME = 'banker';
+const REPO_URL = 'https://github.com/smallOpenSource/banker_plugins';
 
 function version() {
   try { return require(path.join(PKG_ROOT, 'package.json')).version; } catch { return '0.0.0'; }
@@ -25,9 +27,10 @@ function log(...a) { console.log(...a); }
 function warn(...a) { console.error(...a); }
 
 function parseArgs(argv) {
-  const a = { cmd: null, claude: false, codex: false, scope: 'user', scopeExplicit: false, dryRun: false, help: false, version: false };
+  const a = { cmd: null, sub: null, claude: false, codex: false, scope: 'user', scopeExplicit: false, dryRun: false, help: false, version: false };
   for (const t of argv) {
-    if (t === 'setup' || t === 'doctor' || t === 'uninstall' || t === 'help') { if (!a.cmd) a.cmd = t; }
+    if (t === 'setup' || t === 'doctor' || t === 'uninstall' || t === 'help' || t === 'telemetry') { if (!a.cmd) a.cmd = t; }
+    else if (t === 'on' || t === 'off' || t === 'status') { if (!a.sub) a.sub = t; } // telemetry subcommand
     else if (t === '--claude') a.claude = true;
     else if (t === '--codex') a.codex = true;
     else if (t === '--dry-run' || t === '-n') a.dryRun = true;
@@ -228,11 +231,111 @@ function uninstallCodex(dryRun, scopes) {
   }
 }
 
+/* ---------- telemetry config bridge ---------- */
+// bin/banker.js is CommonJS; telemetry-config is ESM (.mjs). Load it lazily via dynamic import
+// (pathToFileURL keeps the specifier valid on Windows). Only the interactive setup path and the
+// telemetry subcommand call this, so the non-TTY / dry-run setup path never imports it.
+async function loadTelemetry() {
+  return import(pathToFileURL(path.join(__dirname, 'lib', 'telemetry-config.mjs')).href);
+}
+
+/* ---------- setup first-run prompts (US-6) ---------- */
+// Interactive-only. ABSOLUTE rule: never prompt or persist in a non-TTY / CI / dry-run context.
+// scripts/smoke-test.js runs `setup --claude --dry-run` non-interactively; a blocking read here
+// would hang CI forever. The isTTY + dryRun guard below is the single gate that prevents that.
+async function maybeFirstRunPrompts(a) {
+  if (!process.stdin.isTTY || a.dryRun) return;                     // non-TTY / CI / dry-run: do nothing
+  const tc = await loadTelemetry();
+  const cfg = tc.readConfig();
+  const askStar = cfg.promptedStarV1 !== true;
+  // count-default-on: 카운팅은 opt-in 질문이 아니라 투명 고지(차단 프롬프트 아님). --claude 관여 시에만 1회 출력.
+  const showTelemetryNotice = a.claude && cfg.promptedTelemetryV2 !== true;
+  if (!askStar && !showTelemetryNotice) return;                     // already shown before - never re-show
+
+  const readline = require('readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise((res) => rl.question(q, res));
+  const next = { ...cfg };
+  try {
+    if (askStar) {
+      const ans = (await ask('banker가 유용했다면 GitHub 별(star)을 눌러 주세요. [Y/n] ')).trim().toLowerCase();
+      if (ans === '' || ans === 'y' || ans === 'yes') {
+        log('감사합니다. 아래 주소에서 직접 별을 눌러 주세요 (자동으로 누르지 않고 안내만 합니다):');
+        log(`  ${REPO_URL}`);
+      }
+      next.promptedStarV1 = true;
+    }
+    if (showTelemetryNotice) {
+      log('banker 는 익명 사용량 카운트를 기본 수집합니다(스킬별 호출수·버전·OS·식별자 없음).');
+      log('끄려면 BANKER_NO_TELEMETRY=1 또는 `banker telemetry off`. 자세히: PRIVACY.md');
+      next.promptedTelemetryV2 = true;
+    }
+  } finally {
+    rl.close();
+  }
+  tc.writeConfig(next);
+}
+
+/* ---------- telemetry subcommand (US-08, count-default-on) ---------- */
+const TELEMETRY_USAGE = `Usage: banker telemetry <on|off|status>
+  on      카운팅 opt-out 을 해제 (기본값인 켜짐으로 복귀)
+  off     카운팅을 끔 (config.telemetry=false 로 opt-out)
+  status  카운팅 / 업데이트-체크의 opt-out · 엔드포인트 · 캐시 상태를 정직하게 출력`;
+
+async function telemetryCmd(sub) {
+  const tc = await loadTelemetry();
+  if (sub === 'on' || sub === 'off') {
+    const cfg = tc.readConfig();
+    if (sub === 'off') cfg.telemetry = false;                        // opt-out 저장
+    else delete cfg.telemetry;                                       // opt-out 해제: 기본-on 으로 복귀
+    if (!tc.writeConfig(cfg)) {
+      warn('banker: 설정을 저장하지 못했습니다 (config 쓰기 실패).');
+      process.exitCode = 1;
+      return;
+    }
+    if (sub === 'off') {
+      log('카운팅을 껐습니다 (off). config.telemetry=false 로 opt-out 을 저장했습니다.');
+    } else {
+      log('카운팅 opt-out 을 해제했습니다 (on). 기본값(켜짐)으로 복귀합니다.');
+      if (!tc.endpoint()) log('참고: 엔드포인트가 설정되어 있지 않아 지금은 아무것도 전송하지 않습니다.');
+    }
+    return;
+  }
+  if (sub === 'status') {
+    const cfg = tc.readConfig();
+    const v = process.env.BANKER_NO_TELEMETRY;
+    const envOptOut = !(v === undefined || v === '' || v === '0' || v === 'false');
+    const cfgOptOut = cfg.telemetry === false;
+    log('banker 상태:');
+    log('[카운팅] 익명 사용량 카운팅 (기본값: 켜짐 · count-default-on)');
+    log(`  엔드포인트 설정: ${tc.endpoint() != null ? '설정됨' : '미설정'}`);
+    log(`  opt-out(BANKER_NO_TELEMETRY): ${envOptOut ? '적용됨' : '미적용'}`);
+    log(`  opt-out(config.telemetry=false): ${cfgOptOut ? '적용됨' : '미적용'}`);
+    log(`  실효 상태(effective): ${tc.countingActive() ? 'enabled' : 'disabled'}`);
+    log('  참고: 엔드포인트가 설정되어 있고 opt-out 이 아닐 때(env·config 둘 다 아님)만 실제로 전송됩니다.');
+
+    let cache = {};
+    try { cache = JSON.parse(fs.readFileSync(tc.UPDATE_CHECK_PATH, 'utf8')); } catch { /* 캐시 없음/malformed */ }
+    const installed = tc.installedVersion();
+    const cmp = (cache.latest && installed) ? tc.compareVersions(cache.latest, installed) : null;
+    log('[업데이트 체크] 새 버전 알림 (기본값: 켜짐)');
+    log(`  opt-out(BANKER_NO_UPDATE_CHECK/config.updateCheck=false): ${tc.noUpdateCheck() ? '적용됨' : '미적용'}`);
+    log(`  마지막 체크: ${cache.checkedAt ? new Date(cache.checkedAt).toISOString() : '없음'}`);
+    log(`  캐시된 최신 버전: ${cache.latest || '없음'} / 설치된 버전: ${installed || '알 수 없음'}`);
+    log(cmp === null ? '  비교 불가 (캐시 없음 또는 malformed)'
+      : cmp > 0 ? `  업데이트 있음 (${installed} → ${cache.latest})`
+      : '  최신 버전 사용 중');
+    return;
+  }
+  log(TELEMETRY_USAGE);                                              // 알 수 없는 하위명령: 사용법 출력
+}
+
 const HELP = `banker v${version()} — install the banker plugin into Claude Code and/or Codex CLI
 
 Usage:
   banker setup [--claude] [--codex] [--scope user|project] [--dry-run]
   banker uninstall [--claude] [--codex] [--scope user|project] [--dry-run]
+  banker telemetry <on|off|status>
   banker doctor
   banker help
 
@@ -240,18 +343,22 @@ Notes:
   - setup/uninstall with no target flag applies to BOTH tools.
   - --claude registers the marketplace + installs banker@banker-plugins (skills as /banker:*).
   - --codex copies codex-eligible skills -> ~/.codex/skills/banker-* and commands -> ~/.codex/prompts/banker-*.md.
+  - telemetry on|off toggles anonymous usage counting opt-out (default-on; config only); status prints counting + update-check state. See PRIVACY.md.
   - Never runs as root. --dry-run prints planned actions without writing.`;
 
-function main() {
+async function main() {
   const a = parseArgs(process.argv.slice(2));
   if (a.version) { log(version()); return; }
   if (a.help || a.cmd === 'help' || !a.cmd) { log(HELP); return; }
   if (a.cmd === 'doctor') { doctor(); return; }
+  if (a.cmd === 'telemetry') { await telemetryCmd(a.sub); return; }
   assertNotRoot();
   if (a.cmd === 'setup') {
     log(`banker setup${a.dryRun ? ' (dry-run)' : ''}: claude=${a.claude} codex=${a.codex}`);
     if (a.claude) setupClaude(a.dryRun);
     if (a.codex) setupCodex(a.dryRun, a.scope);
+    // Best-effort first-run prompts (interactive TTY only). A prompt failure must never fail setup.
+    try { await maybeFirstRunPrompts(a); } catch { /* non-fatal */ }
     log('done.');
     return;
   }
@@ -262,4 +369,4 @@ function main() {
     return;
   }
 }
-main();
+main().catch((e) => { warn('banker:', e && e.message ? e.message : e); process.exitCode = 1; });

package/bin/lib/telemetry-config.mjs

@@ -0,0 +1,271 @@
+/*
+ * telemetry-config - banker 텔레메트리 config/consent 공용 모듈 (bin·hook 공유).
+ * 의존성 0 (Node 내장 모듈만: node:fs, node:path, node:os). ESM(.mjs).
+ * import 시 부작용 없음: 경로는 resolver 로 호출 시 계산하고, 파일시스템 접근·mkdir 은
+ * 각 함수 호출 시에만 일어난다. readConfig/isEnabled/endpoint 는 어떤 예외도 밖으로 던지지 않는다.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+// 단일 config-path resolver. 호출 시점의 env 를 읽어 계산한다 (테스트는 XDG_CONFIG_HOME 으로 격리).
+export function configDir() {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  if (xdg) return path.join(xdg, 'banker');
+  if (process.platform === 'win32') {
+    return path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'), 'banker');
+  }
+  return path.join(os.homedir(), '.config', 'banker');
+}
+
+// 공유 경로 상수: import 시점의 resolver 결과를 캡처한다 (bin·hook 은 단명 프로세스라 env 안정적).
+// 순수 경로 계산이라 파일시스템을 건드리지 않는다. 내부 함수는 configDir() 를 매 호출 재계산하므로
+// 테스트가 XDG_CONFIG_HOME 을 바꿔도 올바르게 격리된다.
+export const USAGE_LOG_PATH = path.join(configDir(), 'usage-log');   // 사용량 로그 절대경로
+export const LAST_FLUSH_PATH = path.join(configDir(), 'last-flush');
+// USAGE_LOG 계약: 한 줄 = `<skill-name>\t<hour 0-23>` (스킬 이름 + TAB + 기록 시각의 로컬 hour).
+// flush 는 이 줄들을 스킬별 x 시간대별로 집계한다. LOG_MAX_LINES 는 (필드 아닌) 줄 수 상한이며,
+// 초과 시 오래된 줄부터 잘라내 24h 윈도우를 근사한다.
+export const LOG_MAX_LINES = 5000;
+
+// 개인화 알림용 로컬 "써 본 스킬" 집합 경로 + 상한. 이 파일은 절대 전송하지 않는다(로컬 전용).
+// update-checkin 페이로드는 usage-log 집계만 담고 이 집합은 건드리지 않는다. update-notify 만 읽는다.
+export const USED_SKILLS_PATH = path.join(configDir(), 'used-skills.json');
+export const USED_SKILLS_MAX = 300;
+
+// update-check 캐시 파일({latest,checkedAt,notified})의 절대경로. USAGE_LOG_PATH 와 동일하게
+// import 시점 resolver 결과를 캡처한다(단명 hook 프로세스용). writeUpdateCache 는 테스트 격리를 위해
+// configDir() 를 매 호출 재계산하므로 이 상수에 의존하지 않는다.
+export const UPDATE_CHECK_PATH = path.join(configDir(), 'update-check.json');
+// 업데이트 체크/체크인 스로틀 창(24h). 이 간격 미경과면 재조회하지 않는다.
+export const UPDATE_THROTTLE_MS = 24 * 60 * 60 * 1000;
+// 최신 버전 조회용 공개 npm 레지스트리 URL. 본문 .version 을 직접 반환한다(실측 확정).
+export const NPM_LATEST_URL = 'https://registry.npmjs.org/@kaydash9999/banker-plugins/latest';
+// 버전별 "바뀐 스킬 목록" 매니페스트(공개 GitHub raw JSON: {"x.y.z": ["banker:skill", ...]}). update-fetch/
+// update-checkin 이 best-effort GET 해 changedSkills 를 캐시에 채우고, update-notify 가 로컬 "써 본 스킬"과
+// 교차해 개인화 알림을 만든다. GET 뿐이라 페이로드/식별자 전송이 없고, 실패해도 무해하다(일반 알림으로 폴백).
+// 테스트는 BANKER_SKILL_CHANGES_URL 로 loopback mock 을 주입해 실제 네트워크를 때리지 않는다.
+export const SKILL_CHANGES_URL = 'https://raw.githubusercontent.com/smallOpenSource/banker_plugins/main/skill-changes.json';
+
+// config.json 을 읽어 객체로 반환. 파일 없음·malformed JSON·권한 오류 등 어떤 예외에도 던지지 않고 {} 반환.
+export function readConfig() {
+  try {
+    const raw = fs.readFileSync(path.join(configDir(), 'config.json'), 'utf8');
+    const obj = JSON.parse(raw);
+    return (obj && typeof obj === 'object' && !Array.isArray(obj)) ? obj : {};
+  } catch {
+    return {};
+  }
+}
+
+// configDir 을 mkdir -p 후 config.json 에 기록. 오류는 삼켜 false, 성공 true.
+export function writeConfig(obj) {
+  try {
+    const target = configDir();
+    fs.mkdirSync(target, { recursive: true });
+    fs.writeFileSync(path.join(target, 'config.json'), JSON.stringify(obj, null, 2));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// 배포에 내장하는 기본 카운팅 엔드포인트(유지보수자가 운영하는 Cloudflare Worker). 이 상수를 내장해서
+// count-default-on 이 모든 설치에서 활성이다: endpoint() 가 (거의) 항상 값을 반환하므로 countingActive()
+// 가 기본 켜짐이 되고, opt-out(BANKER_NO_TELEMETRY / banker telemetry off / config.telemetry=false)으로만
+// 끈다. 자가호스팅/override 는 BANKER_TELEMETRY_ENDPOINT env 로 한다.
+export const DEFAULT_ENDPOINT = 'https://banker.banker-plugins.workers.dev/';
+
+// 카운팅 엔드포인트 문자열. 우선순위: env(BANKER_TELEMETRY_ENDPOINT) > config.endpoint > DEFAULT_ENDPOINT.
+// 기본 엔드포인트를 내장하므로 env·config 미설정이어도 DEFAULT_ENDPOINT 를 반환한다(= count-default-on 이
+// 모든 설치에서 활성, opt-out 으로만 끔). env 빈문자열('')은 falsy 라 여전히 config/DEFAULT 로 흐른다.
+// 예외가 난 경우에만 null 을 반환한다(에러 시 보수적으로 전송 안 함).
+export function endpoint() {
+  try {
+    const env = process.env.BANKER_TELEMETRY_ENDPOINT;
+    if (env) return env;
+    const ep = readConfig().endpoint;
+    return (typeof ep === 'string' && ep) ? ep : DEFAULT_ENDPOINT;
+  } catch {
+    return null;
+  }
+}
+
+// env 값이 opt-out 을 의미하는지. unset·''·'0'·'false' 는 opt-out 이 아니고, 그 외 모든 값이 opt-out.
+// BANKER_NO_TELEMETRY 와 BANKER_NO_UPDATE_CHECK 가 동일 규칙을 공유한다.
+function isOptOut(v) {
+  return !(v === undefined || v === '' || v === '0' || v === 'false');
+}
+
+// BANKER_NO_TELEMETRY 가 opt-out 을 의미하는지.
+function noTelemetry() {
+  return isOptOut(process.env.BANKER_NO_TELEMETRY);
+}
+
+// [예약] opt-in 게이트. 현재 카운팅은 countingActive(default-on)를 쓰므로 프로덕션 호출자는 없다.
+// 향후 EU 등에서 opt-in 전환이 필요할 때(PRIVACY.md 법적 상태 참조) 재도입할 수 있게 보존한다.
+// 다음이 전부 참일 때만 true: (1) readConfig().telemetry===true, (2) 엔드포인트 설정됨,
+// (3) BANKER_NO_TELEMETRY 가 opt-out 아님. 전체를 try/catch 로 감싸 어떤 예외에도 false.
+export function isEnabled() {
+  try {
+    if (readConfig().telemetry !== true) return false;
+    if (!endpoint()) return false;
+    if (noTelemetry()) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// 업데이트 체크를 opt-out 했는지. env BANKER_NO_UPDATE_CHECK 가 opt-out 이거나
+// readConfig().updateCheck===false 이면 true. 전체를 try/catch 로 감싸 어떤 예외에도 false.
+export function noUpdateCheck() {
+  try {
+    if (isOptOut(process.env.BANKER_NO_UPDATE_CHECK)) return true;
+    if (readConfig().updateCheck === false) return true;
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+// 익명 사용량 카운팅이 활성인지 (default-on). isEnabled 의 opt-in(telemetry===true) 과 달리
+// telemetry 미설정도 활성으로 본다: (1) 엔드포인트 설정됨, (2) BANKER_NO_TELEMETRY 가 opt-out 아님,
+// (3) readConfig().telemetry!==false. 셋 다 참이면 true. 전체를 try/catch 로 감싸 어떤 예외에도 false.
+export function countingActive() {
+  try {
+    if (!endpoint()) return false;
+    if (noTelemetry()) return false;
+    if (readConfig().telemetry === false) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// 이 모듈 파일 기준 플러그인 루트의 plugin.json 절대경로 (bin/lib -> 루트 = 두 단계 위).
+// fileURLToPath·path 는 순수 계산이라 import 부작용이 없다(파일 읽기는 installedVersion 호출 시에만).
+const PLUGIN_JSON_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '.claude-plugin', 'plugin.json');
+
+// 설치된 플러그인 버전 문자열. 기본 경로는 플러그인 루트의 .claude-plugin/plugin.json 이며,
+// 테스트가 임의 경로를 주입할 수 있게 파라미터로도 받는다. 파일없음·malformed·비문자열·빈문자열 → null.
+export function installedVersion(pluginJsonPath = PLUGIN_JSON_PATH) {
+  try {
+    const v = JSON.parse(fs.readFileSync(pluginJsonPath, 'utf8')).version;
+    return (typeof v === 'string' && v) ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+// 'x.y.z' 두 버전을 major.minor.patch 정수 3튜플로 비교한다. a>b 면 양수, a<b 면 음수, 같으면 0.
+// prerelease 접미사('1.2.3-rc1')·토큰 누락('1.2')·비수치('a.b.c')가 있으면 null(미확정) 반환.
+// 순수 함수이며 어떤 입력에도 throw 하지 않는다.
+export function compareVersions(a, b) {
+  const parse = (s) => {
+    if (typeof s !== 'string') return null;
+    const parts = s.split('.');
+    if (parts.length !== 3) return null;
+    const nums = [];
+    for (const part of parts) {
+      if (!/^\d+$/.test(part)) return null; // 빈·비수치·prerelease('3-rc1') 토큰 배제
+      nums.push(Number(part));
+    }
+    return nums;
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  if (pa === null || pb === null) return null;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] !== pb[i]) return pa[i] - pb[i];
+  }
+  return 0;
+}
+
+// update-check 캐시를 read-modify-write 로 병합 기록한다: 기존 JSON 을 읽어({} on 실패) patch 의
+// 필드만 덮고 나머지 형제 필드는 보존한 뒤, configDir() mkdir -p → temp 파일 쓰기 → rename(원자적)
+// 으로 기록한다. 테스트 격리를 위해 경로는 configDir() 로 매 호출 재계산한다(UPDATE_CHECK_PATH 상수
+// 비의존). 모든 오류를 삼켜 best-effort: 성공 true, 실패 false.
+export function writeUpdateCache(patch) {
+  try {
+    const dir = configDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const cachePath = path.join(dir, 'update-check.json');
+    let existing = {};
+    try {
+      const obj = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+      if (obj && typeof obj === 'object' && !Array.isArray(obj)) existing = obj;
+    } catch { /* 없음·malformed → {} */ }
+    const merged = { ...existing, ...(patch && typeof patch === 'object' && !Array.isArray(patch) ? patch : {}) };
+    const tmp = path.join(dir, `update-check.json.${process.pid}.tmp`);
+    fs.writeFileSync(tmp, JSON.stringify(merged, null, 2));
+    fs.renameSync(tmp, cachePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---- 개인화 알림용 로컬 "써 본 스킬" 집합 (전송하지 않음) ----
+// 이 집합은 절대 서버로 보내지 않는다: update-checkin 페이로드는 usage-log 집계(counts)만 담는다.
+// update-notify 가 로컬에서 읽어, 새 버전에서 바뀐 스킬 중 "사용자가 써 본 것"만 골라 알림에 이름을 넣는다.
+
+// 로컬 "써 본 스킬" 배열을 반환. 없음·malformed·비배열 → []. 문자열 원소만 남긴다. 어떤 오류에도 [].
+export function readUsedSkills() {
+  try {
+    const arr = JSON.parse(fs.readFileSync(path.join(configDir(), 'used-skills.json'), 'utf8'));
+    return Array.isArray(arr) ? arr.filter((x) => typeof x === 'string' && x) : [];
+  } catch {
+    return [];
+  }
+}
+
+// name 을 로컬 집합에 union 한다(개인화 알림용, 전송 안 함). 이미 있으면 파일을 쓰지 않는다(핫패스 절약).
+// 상한(USED_SKILLS_MAX) 도달 시 새 이름은 무시한다(오래된 것 보존; 개인화는 근사여도 무방). configDir() 를
+// 매 호출 재계산(테스트 격리) + temp→rename 원자적 기록. 모든 오류를 삼켜 신규 기록 시 true, 그 외 false.
+export function recordUsedSkill(name) {
+  try {
+    if (typeof name !== 'string' || !name) return false;
+    const set = readUsedSkills();
+    if (set.includes(name)) return false;            // 이미 기록됨 - 쓰지 않는다.
+    if (set.length >= USED_SKILLS_MAX) return false;  // 상한 - 무시.
+    set.push(name);
+    const dir = configDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const target = path.join(dir, 'used-skills.json');
+    const tmp = path.join(dir, `used-skills.json.${process.pid}.tmp`);
+    fs.writeFileSync(tmp, JSON.stringify(set));
+    fs.renameSync(tmp, target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// 순수 함수: 버전->바뀐 스킬 배열 map 에서 installed < v <= latest 인 버전들의 스킬을 합쳐 중복 제거해 반환.
+// map 비객체·installed/latest 비문자열 → []. malformed 버전 키(compareVersions null)·비배열 값은 건너뛴다.
+// 어떤 입력에도 throw 하지 않는다. 개인화가 "설치~최신 사이에 바뀐 스킬"을 계산하는 데 쓴다.
+export function changedSkillsBetween(map, installed, latest) {
+  try {
+    if (!map || typeof map !== 'object' || Array.isArray(map)) return [];
+    if (typeof installed !== 'string' || typeof latest !== 'string') return [];
+    const seen = new Set();
+    const out = [];
+    for (const v of Object.keys(map)) {
+      const gt = compareVersions(v, installed);
+      const le = compareVersions(v, latest);
+      if (gt === null || le === null) continue;   // malformed 버전 키 무시.
+      if (gt > 0 && le <= 0) {
+        const skills = map[v];
+        if (!Array.isArray(skills)) continue;
+        for (const s of skills) {
+          if (typeof s === 'string' && s && !seen.has(s)) { seen.add(s); out.push(s); }
+        }
+      }
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}