@kaydash9999/banker-plugins 0.7.1 → 0.9.0

package/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "banker obsidizer: canonicalize an OMC wiki page right after it is written, but only when the vault is armed via `obsidizer --enable`. Inert otherwise.",
+  "description": "banker hooks: obsidizer wiki canonicalization (PostToolUse, inert until `obsidizer --enable`) + anonymous usage counting (PostToolUse Skill / UserPromptExpansion, count-default-on, opt-out BANKER_NO_TELEMETRY, no-op without endpoint) + update-check notification (SessionStart, opt-out BANKER_NO_UPDATE_CHECK).",
   "hooks": {
     "PostToolUse": [
       {
@@ -11,6 +11,40 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PLUGIN_ROOT\"/hooks/run.cjs \"$CLAUDE_PLUGIN_ROOT\"/hooks/telemetry-count-skill.mjs",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "UserPromptExpansion": [
+      {
+        "matcher": "banker:.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PLUGIN_ROOT\"/hooks/run.cjs \"$CLAUDE_PLUGIN_ROOT\"/hooks/telemetry-count.mjs",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PLUGIN_ROOT\"/hooks/run.cjs \"$CLAUDE_PLUGIN_ROOT\"/hooks/update-notify.mjs",
+            "timeout": 5
+          }
+        ]
       }
     ]
   }

package/hooks/telemetry-count-skill.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/*
+ * banker 텔레메트리 count 훅 (PostToolUse, matcher: Skill) - 모델이 자동 호출한
+ * banker:<name> 스킬을 로컬 usage-log 에 `<name>\t<hour>` 한 줄로 기록한다.
+ *
+ * fail-closed 규약(각 항목은 telemetry-count-skill.test.mjs 가 검증한다):
+ *  - countingActive() 가 아니면 로컬 쓰기조차 하지 않는다. 파일도 만들지 않는다.
+ *  - 어떤 오류도 삼키고 항상 exit 0. 세션/툴호출을 절대 막지 않는다.
+ *  - PII/식별자를 다루지 않는다. 로그 한 줄 = 이름 문자열 + TAB + hour(0-23) 뿐이다.
+ *
+ * payload 필드 확정(US-4 라이브 스모크테스트): PostToolUse(Skill) stdin payload 는
+ * `tool_input.skill`(예: "banker:compact-copy")을 담는다. 보조 소스로
+ * `tool_response.commandName` 도 시도한다. 사용자가 /banker:* 를 직접 호출한 경우는
+ * UserPromptExpansion 쪽(telemetry-count.mjs)이 담당한다 - 두 경로는 disjoint 로 실측
+ * 확정되어 dedup 이 불요하다.
+ *
+ * 체크인(usage-log 집계 후 서버 전송)은 이 훅의 책임이 아니다. 트리거는 SessionStart
+ * update-notify 가 throttle 경과 시 별도로 연다 - 이 훅은 append 만 하고 flush/checkin 을
+ * spawn 하지 않는다.
+ *
+ * 배선: hooks.json 의 PostToolUse(matcher Skill)에 등록되어 모델 자동 스킬 호출 시 발화한다.
+ */
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+
+import { configDir, countingActive, recordUsedSkill, USAGE_LOG_PATH, LOG_MAX_LINES } from '../bin/lib/telemetry-config.mjs';
+
+// banker:<name> 전체 일치 - 이름 문자열 자체를 검증한다(TAB/개행 등 이질 문자가 섞여
+// usage-log 의 `name\thour` 형식을 깨는 것을 막는다). i 플래그는 매칭만 관대하게(실제 이름은 소문자).
+const NAME_RE = /^banker:[a-z0-9_-]+$/i;
+
+function readStdin() {
+  return new Promise((resolvePromise, rejectPromise) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolvePromise(data));
+    process.stdin.on('error', rejectPromise);
+  });
+}
+
+// PostToolUse(Skill) payload 에서 모델이 자동 호출한 banker:<name> 스킬 이름을 추출한다.
+// 주 소스는 tool_input.skill, 없거나 미매치면 보조로 tool_response.commandName 을 시도한다.
+function extractName(payload) {
+  const candidates = [payload?.tool_input?.skill, payload?.tool_response?.commandName];
+  for (const c of candidates) {
+    if (typeof c === 'string' && NAME_RE.test(c)) return c;
+  }
+  return null;
+}
+
+// 파일의 개행 개수 = 줄 수(각 append 가 끝에 개행을 붙이므로). 없거나 읽기 실패면 0.
+function lineCount(path) {
+  try {
+    const raw = readFileSync(path, 'utf8');
+    return (raw.match(/\n/g) || []).length;
+  } catch {
+    return 0;
+  }
+}
+
+// usage-log 에 `<name>\t<hour>` 한 줄을 append 한다(hour = 로컬 시각 0-23). 상한 도달 시
+// 스킵(best-effort; 체크인이 비우면 재개). flush/checkin 은 여기서 spawn 하지 않는다
+// (트리거는 SessionStart update-notify 소관).
+function record(name) {
+  try { mkdirSync(configDir(), { recursive: true }); } catch { /* best-effort */ }
+  try {
+    if (lineCount(USAGE_LOG_PATH) < LOG_MAX_LINES) {
+      const hour = new Date().getHours();
+      appendFileSync(USAGE_LOG_PATH, `${name}\t${hour}\n`);
+    }
+  } catch { /* best-effort */ }
+}
+
+async function main() {
+  let raw;
+  try {
+    raw = await readStdin();
+  } catch {
+    return; // stdin 읽기 실패 - 무동작.
+  }
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    return; // malformed stdin - 무동작.
+  }
+  if (!countingActive()) return; // 카운팅 비활성 - 로컬 쓰기조차 하지 않는다.
+  const name = extractName(payload);
+  if (!name) return; // banker:<name> 아님 - 무동작.
+  record(name);            // 서버 카운팅용 usage-log append (스킬별 x 시간대 버킷).
+  recordUsedSkill(name);   // 개인화 알림용 로컬 집합 union (전송 안 함; update-notify 만 로컬에서 읽는다).
+}
+
+main()
+  .catch(() => {}) // 어떤 예외도 세션을 막지 않는다.
+  .finally(() => process.exit(0));

package/hooks/telemetry-count.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/*
+ * banker 텔레메트리 count 훅 (UserPromptExpansion) - 사용자가 직접 호출한 /banker:<name>
+ * 커맨드를 로컬 usage-log 에 `<name>\t<hour>` 한 줄로 기록한다.
+ *
+ * fail-closed 규약(각 항목은 telemetry-count.test.mjs 가 검증한다):
+ *  - countingActive() 가 아니면 로컬 쓰기조차 하지 않는다. 파일도 만들지 않는다.
+ *  - 어떤 오류도 삼키고 항상 exit 0. 세션/프롬프트를 절대 막지 않는다.
+ *  - PII/식별자를 다루지 않는다. 로그 한 줄 = 이름 문자열 + TAB + hour(0-23) 뿐이다.
+ *
+ * payload 필드 확정(US-4 라이브 스모크테스트): UserPromptExpansion stdin payload 는
+ * `command_name`(예: "banker:setup-lsp")과 `command_source`("plugin")를 담는다. 사용자가
+ * /banker:* 를 직접 호출한 경우만 이 이벤트가 발화하고, 모델이 자동 호출하는 스킬은
+ * PostToolUse(Skill) 쪽(telemetry-count-skill.mjs)이 담당한다 - 두 경로는 disjoint 로 실측
+ * 확정되어 dedup 이 불요하다. 더 이상 방어적 다중필드 추출이 필요 없다.
+ *
+ * 체크인(usage-log 집계 후 서버 전송)은 이 훅의 책임이 아니다. 트리거는 SessionStart
+ * update-notify 가 throttle 경과 시 별도로 연다 - 이 훅은 append 만 하고 flush/checkin 을
+ * spawn 하지 않는다.
+ *
+ * 배선: hooks.json 의 UserPromptExpansion(matcher banker:.*)에 등록되어 사용자 직접 /banker:* 호출 시 발화한다.
+ */
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+
+import { configDir, countingActive, recordUsedSkill, USAGE_LOG_PATH, LOG_MAX_LINES } from '../bin/lib/telemetry-config.mjs';
+
+// banker:<name> 전체 일치 - 이름 문자열 자체를 검증한다(TAB/개행 등 이질 문자가 섞여
+// usage-log 의 `name\thour` 형식을 깨는 것을 막는다). i 플래그는 매칭만 관대하게(실제 이름은 소문자).
+const NAME_RE = /^banker:[a-z0-9_-]+$/i;
+
+function readStdin() {
+  return new Promise((resolvePromise, rejectPromise) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolvePromise(data));
+    process.stdin.on('error', rejectPromise);
+  });
+}
+
+// UserPromptExpansion payload 에서 사용자가 직접 호출한 banker:<name> 이름을 추출한다.
+// command_source 가 'plugin' 이고 command_name 이 banker:<name> 형식일 때만 반환, 그 외 null.
+function extractName(payload) {
+  if (payload?.command_source !== 'plugin') return null;
+  const name = payload?.command_name;
+  return (typeof name === 'string' && NAME_RE.test(name)) ? name : null;
+}
+
+// 파일의 개행 개수 = 줄 수(각 append 가 끝에 개행을 붙이므로). 없거나 읽기 실패면 0.
+function lineCount(path) {
+  try {
+    const raw = readFileSync(path, 'utf8');
+    return (raw.match(/\n/g) || []).length;
+  } catch {
+    return 0;
+  }
+}
+
+// usage-log 에 `<name>\t<hour>` 한 줄을 append 한다(hour = 로컬 시각 0-23). 상한 도달 시
+// 스킵(best-effort; 체크인이 비우면 재개). flush/checkin 은 여기서 spawn 하지 않는다
+// (트리거는 SessionStart update-notify 소관).
+function record(name) {
+  try { mkdirSync(configDir(), { recursive: true }); } catch { /* best-effort */ }
+  try {
+    if (lineCount(USAGE_LOG_PATH) < LOG_MAX_LINES) {
+      const hour = new Date().getHours();
+      appendFileSync(USAGE_LOG_PATH, `${name}\t${hour}\n`);
+    }
+  } catch { /* best-effort */ }
+}
+
+async function main() {
+  let raw;
+  try {
+    raw = await readStdin();
+  } catch {
+    return; // stdin 읽기 실패 - 무동작.
+  }
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    return; // malformed stdin - 무동작.
+  }
+  if (!countingActive()) return; // 카운팅 비활성 - 로컬 쓰기조차 하지 않는다.
+  const name = extractName(payload);
+  if (!name) return; // banker:<name> 아님 - 무동작.
+  record(name);            // 서버 카운팅용 usage-log append (스킬별 x 시간대 버킷).
+  recordUsedSkill(name);   // 개인화 알림용 로컬 집합 union (전송 안 함; update-notify 만 로컬에서 읽는다).
+}
+
+main()
+  .catch(() => {}) // 어떤 예외도 세션을 막지 않는다.
+  .finally(() => process.exit(0));

package/hooks/update-checkin.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+/*
+ * banker 카운팅 체크인 훅 - usage-log 를 스킬별 x 시간대(hour 0-23)별 count 로 집계해 엔드포인트로
+ * 한 번 POST 하고, 응답의 latest 로 update-check 캐시를 겸해 갱신한다. 전송 시도 후(성공/실패 무관)
+ * 로그를 truncate 해 24h 윈도우로 상한한다. telemetry-flush 를 대체(evolve)한다.
+ *
+ * fail-closed 규약(각 항목은 update-checkin.test.mjs 가 검증한다):
+ *  - 미활성(countingActive) 또는 엔드포인트 없음이면 무동작(로그도 건드리지 않는다).
+ *  - PII/IP/지속ID 절대 미포함. 페이로드는 {version, os, counts} 세 키뿐(os=플랫폼 계열,
+ *    counts=스킬별 x 시간대별 호출수).
+ *  - 자체 네트워크 timeout 으로 hang 방지. 어떤 오류도 삼키고 항상 exit 0. 어떤 경로도 reject 안 함.
+ *  - 비-loopback 평문 http 는 전송하지 않는다(https-only). loopback http 만 로컬 테스트 mock 에 허용.
+ *
+ * count-default-on: 이 훅은 hooks.json 에 배선되지 않는다(스탠드얼론 .mjs). update-notify 가
+ * countingActive + 엔드포인트 설정 시 fetcher 로 detached spawn 한다(응답 latest 가 알림 캐시를 겸함).
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import http from 'node:http';
+import https from 'node:https';
+
+import {
+  countingActive,
+  endpoint,
+  USAGE_LOG_PATH,
+  LAST_FLUSH_PATH,
+  SKILL_CHANGES_URL,
+  installedVersion,
+  writeUpdateCache,
+  changedSkillsBetween,
+} from '../bin/lib/telemetry-config.mjs';
+
+const NET_TIMEOUT_MS = 10_000;
+
+// usage-log 각 줄 `<name>\t<hour 0-23>` 를 스킬별 x 시간대별 count 로 집계한다.
+// 빈 줄·TAB 없는 줄·이름 없는 줄·hour 가 0-23 정수가 아닌 줄은 무시한다.
+// 반환 예: { 'banker:compact-copy': { '9': 3, '14': 1 }, 'banker:setup': { '9': 1 } }.
+function aggregate(raw) {
+  const counts = {};
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;              // 빈 줄 무시.
+    const tab = line.indexOf('\t');
+    if (tab < 0) continue;                    // TAB 없는 malformed 줄 무시.
+    const name = line.slice(0, tab).trim();
+    const hourStr = line.slice(tab + 1).trim();
+    if (!name) continue;                      // 이름 없는 줄 무시.
+    if (!/^\d+$/.test(hourStr)) continue;     // 정수 아닌 hour 무시(음수·소수·비수치 배제).
+    const hour = Number(hourStr);
+    if (hour > 23) continue;                  // 0-23 범위 밖 무시(하한은 \d+ 가 보장).
+    const key = String(hour);                 // '09' -> '9' 정규화.
+    if (!counts[name]) counts[name] = {};
+    counts[name][key] = (counts[name][key] || 0) + 1;
+  }
+  return counts;
+}
+
+// loopback 호스트만 평문 http 를 허용한다(로컬 테스트 mock 전용). update-fetch.mjs 와 동일 판별:
+// URL.hostname 은 IPv6 를 대괄호로 감싸므로([::1]) 벗겨서 비교한다.
+function isLoopback(hostname) {
+  const h = (hostname || '').replace(/^\[|\]$/g, '').toLowerCase();
+  return h === 'localhost' || h === '127.0.0.1' || h === '::1';
+}
+
+// 엔드포인트로 JSON POST. 어떤 경로에서도 reject 하지 않고, 전송 시도가 끝나면 응답 본문(문자열)
+// 또는 null 로 resolve 한다. 자체 timeout(NET_TIMEOUT_MS)으로 무응답 엔드포인트에도 hang 하지 않는다.
+function post(url, body) {
+  return new Promise((resolvePromise) => {
+    let done = false;
+    const finish = (responseBody = null) => { if (!done) { done = true; resolvePromise(responseBody); } };
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch {
+      return finish(); // 잘못된 엔드포인트 - 전송 스킵.
+    }
+    // PRIVACY.md 정합: 비-loopback 엔드포인트에는 https 만 허용한다. 평문 http 는
+    // loopback(localhost/127.0.0.1/::1) 로컬 테스트 mock 에만, http/https 외 스킴은
+    // 전송하지 않고 no-op(fail-closed). 평문 비-loopback 유출을 원천 차단한다.
+    if (parsed.protocol === 'http:') {
+      if (!isLoopback(parsed.hostname)) return finish();
+    } else if (parsed.protocol !== 'https:') {
+      return finish();
+    }
+    const transport = parsed.protocol === 'http:' ? http : https;
+    try {
+      const req = transport.request(parsed, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) },
+      }, (res) => {
+        let data = '';
+        res.on('data', (c) => { data += c; });
+        res.on('end', () => finish(data));
+        res.on('error', () => finish());
+      });
+      req.on('error', () => finish()); // 연결 거부/리셋 등은 즉시 여기로.
+      req.setTimeout(NET_TIMEOUT_MS, () => req.destroy());
+      req.write(body);
+      req.end();
+    } catch {
+      finish();
+    }
+  });
+}
+
+// 응답 본문에서 latest 버전 문자열만 방어 추출. null·비문자열·빈·malformed·비문자열 latest 값 → null.
+function extractLatest(responseBody) {
+  if (typeof responseBody !== 'string' || !responseBody) return null;
+  try {
+    const obj = JSON.parse(responseBody);
+    const v = (obj && typeof obj === 'object') ? obj.latest : undefined;
+    return (typeof v === 'string' && v) ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+// 변경-스킬 매니페스트(공개 GitHub raw JSON: {"x.y.z": ["banker:skill", ...]})를 GET 해 객체로 반환한다.
+// update-fetch 의 동일 함수와 self-contained 로 나란히 둔다(훅별 자기완결 관례·isLoopback 도 이미 각자 보유).
+// post() 와 동일한 안전 가드: 비-https 는 loopback 만 허용·3xx no-op·자체 timeout·malformed→null. 어떤
+// 실패에도 reject 하지 않고 null 로 resolve 한다(개인화는 best-effort). 비배열 객체만 반환.
+function fetchSkillChangesMap(url) {
+  return new Promise((resolvePromise) => {
+    let done = false;
+    const finish = (result) => { if (!done) { done = true; resolvePromise(result); } };
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch {
+      return finish(null);
+    }
+    if (parsed.protocol === 'http:') {
+      if (!isLoopback(parsed.hostname)) return finish(null);
+    } else if (parsed.protocol !== 'https:') {
+      return finish(null);
+    }
+    const transport = parsed.protocol === 'http:' ? http : https;
+    try {
+      const req = transport.request(parsed, { method: 'GET' }, (res) => {
+        const status = res.statusCode || 0;
+        if (status >= 300 && status < 400) { res.resume(); return finish(null); } // 리다이렉트 미추적.
+        let data = '';
+        res.on('data', (c) => { data += c; });
+        res.on('end', () => {
+          try {
+            const obj = JSON.parse(data);
+            finish((obj && typeof obj === 'object' && !Array.isArray(obj)) ? obj : null);
+          } catch {
+            finish(null);
+          }
+        });
+        res.on('error', () => finish(null));
+      });
+      req.on('error', () => finish(null));
+      req.setTimeout(NET_TIMEOUT_MS, () => req.destroy());
+      req.end(); // GET - 요청 본문 없음.
+    } catch {
+      finish(null);
+    }
+  });
+}
+
+async function main() {
+  if (!countingActive()) return; // 미활성 - 무동작(로그 미변경).
+  const url = endpoint();
+  if (!url) return;              // 엔드포인트 없음 - 무동작(로그 미변경).
+
+  // 로그 없음도 유효한 체크인(설치 펄스 + 알림 fetch 겸함): 빈 counts 로 진행한다.
+  let raw = '';
+  try { raw = readFileSync(USAGE_LOG_PATH, 'utf8'); } catch { raw = ''; }
+
+  // PII/IP/지속ID 없음: version + os(플랫폼 계열) + counts(스킬별 x 시간대)뿐.
+  const payload = JSON.stringify({
+    version: installedVersion() || 'unknown',
+    os: process.platform,
+    counts: aggregate(raw),
+  });
+  const responseBody = await post(url, payload);
+
+  // 응답의 latest 로 공유 update-check 캐시를 갱신(알림 겸함). 없으면 캐시 미변경.
+  // update-fetch 처럼 notified:null 재무장을 하지 않아도 등가다: dedupe 판정이 notified===latest
+  // (update-notify)라 전진 버전에서 구 notified 는 항상 신 latest 와 달라 재고지가 정상 발화하고,
+  // count-default-on 은 이 훅만·npm 배포는 update-fetch 만 써 같은 캐시를 겹쳐 쓰지 않는다.
+  const latest = extractLatest(responseBody);
+  if (latest) {
+    // 개인화용: 변경-스킬 매니페스트를 best-effort GET(실패 시 changedSkills 생략, 기존 값 보존).
+    const changesUrl = process.env.BANKER_SKILL_CHANGES_URL || SKILL_CHANGES_URL; // 테스트 주입용 override.
+    const map = await fetchSkillChangesMap(changesUrl);
+    const patch = { latest, checkedAt: Date.now() };
+    if (map) patch.changedSkills = changedSkillsBetween(map, installedVersion(), latest);
+    try { writeUpdateCache(patch); } catch { /* best-effort */ }
+  }
+
+  // 전송 시도 후(성공/실패 무관) 로그를 비워 24h 윈도우로 상한(배치 유실 허용).
+  try { writeFileSync(USAGE_LOG_PATH, ''); } catch { /* best-effort */ }
+  try { writeFileSync(LAST_FLUSH_PATH, new Date().toISOString()); } catch { /* best-effort */ }
+}
+
+main()
+  .catch(() => {}) // 어떤 예외도 삼킨다.
+  .finally(() => process.exit(0));

package/hooks/update-fetch.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/*
+ * banker 업데이트 알림 fetcher 훅 - npm 레지스트리에서 최신 버전을 조회해 update-check 캐시를 갱신한다.
+ * SessionStart 알림 훅(update-notify)이 이 fetcher 를 detached 로 기동해 캐시를 채우고, 알림 렌더링
+ * 자체는 캐시만 읽는 별도 훅이 담당한다(이 파일은 네트워크 조회만 - 화면 출력 없음).
+ *
+ * fail-closed 규약(각 항목은 update-fetch.test.mjs 가 검증한다):
+ *  - throttle(UPDATE_THROTTLE_MS) 미경과면 무동작(캐시가 없으면 진행).
+ *  - 비-https 는 loopback(localhost/127.0.0.1/::1) 에서만 http 허용, 그 외 비-https 는 거부.
+ *  - 3xx 리다이렉트는 따라가지 않고 no-op.
+ *  - 응답 JSON 에서 version 문자열만 방어 추출 - 없거나 비문자열이면 무동작(캐시 미기록).
+ *  - 캐시는 writeUpdateCache 로 병합 기록: fetch 된 latest 가 기존 캐시와 다르면 notified 를 초기화
+ *    (재무장)하고, 같으면 형제 필드(notified 등)를 patch 에서 생략해 그대로 보존한다.
+ *  - 어떤 오류도 삼키고 항상 exit 0. GET 뿐이라 페이로드/식별자 전송이 없다.
+ *
+ * 이 훅은 hooks.json 에 배선되지 않는다(스탠드얼론 .mjs). update-notify 가 detached spawn 한다.
+ */
+import { readFileSync } from 'node:fs';
+import http from 'node:http';
+import https from 'node:https';
+
+import { UPDATE_CHECK_PATH, UPDATE_THROTTLE_MS, NPM_LATEST_URL, writeUpdateCache } from '../bin/lib/telemetry-config.mjs';
+
+const NET_TIMEOUT_MS = 10_000;
+
+// loopback 호스트만 평문 http 를 허용한다(로컬 테스트 mock 전용). update-checkin.mjs 와 동일 판별:
+// URL.hostname 은 IPv6 를 대괄호로 감싸므로([::1]) 벗겨서 비교한다.
+function isLoopback(hostname) {
+  const h = (hostname || '').replace(/^\[|\]$/g, '').toLowerCase();
+  return h === 'localhost' || h === '127.0.0.1' || h === '::1';
+}
+
+// update-check 캐시를 읽어 객체로 반환. 없음·malformed·권한 오류 등 어떤 예외에도 던지지 않고 {} 반환.
+function readCache() {
+  try {
+    const obj = JSON.parse(readFileSync(UPDATE_CHECK_PATH, 'utf8'));
+    return (obj && typeof obj === 'object' && !Array.isArray(obj)) ? obj : {};
+  } catch {
+    return {};
+  }
+}
+
+// url 에 GET 요청해 응답 JSON 의 version 문자열만 추출한다. 실패·거부·리다이렉트·malformed 는 전부
+// null. reject 하지 않고 항상 resolve 한다(hang 방지). GET 뿐이라 페이로드·식별자 헤더가 없다.
+function fetchLatestVersion(url) {
+  return new Promise((resolvePromise) => {
+    let done = false;
+    const finish = (result) => { if (!done) { done = true; resolvePromise(result); } };
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch {
+      return finish(null); // 잘못된 URL - 조회 스킵.
+    }
+    // 비-https 는 loopback 로컬 테스트 mock 에만 허용, 그 외 스킴/호스트는 no-op(fail-closed).
+    if (parsed.protocol === 'http:') {
+      if (!isLoopback(parsed.hostname)) return finish(null);
+    } else if (parsed.protocol !== 'https:') {
+      return finish(null);
+    }
+    const transport = parsed.protocol === 'http:' ? http : https;
+    try {
+      const req = transport.request(parsed, { method: 'GET' }, (res) => {
+        const status = res.statusCode || 0;
+        // 3xx 리다이렉트는 따라가지 않는다: 응답을 흘려보내고 no-op 으로 종료.
+        if (status >= 300 && status < 400) {
+          res.resume();
+          return finish(null);
+        }
+        let data = '';
+        res.on('data', (c) => { data += c; });
+        res.on('end', () => {
+          try {
+            const obj = JSON.parse(data);
+            const v = obj && typeof obj === 'object' ? obj.version : undefined;
+            finish((typeof v === 'string' && v) ? v : null);
+          } catch {
+            finish(null); // 빈/malformed 본문.
+          }
+        });
+        res.on('error', () => finish(null));
+      });
+      req.on('error', () => finish(null)); // 연결 거부/리셋 등은 즉시 여기로.
+      req.setTimeout(NET_TIMEOUT_MS, () => req.destroy());
+      req.end(); // GET - 요청 본문 없음.
+    } catch {
+      finish(null);
+    }
+  });
+}
+
+async function main() {
+  const cache = readCache();
+  const checkedAt = typeof cache.checkedAt === 'number' ? cache.checkedAt : null;
+  if (checkedAt !== null && (Date.now() - checkedAt) < UPDATE_THROTTLE_MS) return; // throttle 미경과 - no-op.
+
+  const url = process.env.BANKER_NPM_URL || NPM_LATEST_URL; // 테스트 주입용 override.
+  const latest = await fetchLatestVersion(url);
+  if (!latest) return; // 조회 실패·거부·malformed - 캐시 미기록.
+
+  // 개인화 매니페스트는 여기서 조회하지 않는다: update-fetch 는 카운팅 opt-out(countingActive false) 경로의
+  // fetcher 이고, 개인화 표시도 countingActive() 로 게이트되므로 이 경로에선 표시될 일이 없다. 매니페스트
+  // 조회는 카운팅 활성 경로의 update-checkin 만 수행한다(중복·죽은 조회 제거).
+  const cachedLatest = typeof cache.latest === 'string' ? cache.latest : null;
+  if (cachedLatest !== latest) {
+    writeUpdateCache({ latest, checkedAt: Date.now(), notified: null }); // 신버전 - notified 재무장.
+  } else {
+    writeUpdateCache({ latest, checkedAt: Date.now() }); // 동일 버전 - notified 등 형제 필드는 병합 보존.
+  }
+}
+
+main()
+  .catch(() => {}) // 어떤 예외도 삼킨다.
+  .finally(() => process.exit(0));