tokenphage 2026.7.0-BETA

package/src/index.js

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+/**
+ * tokenphage CLI 진입점 (package.json "bin"이 가리키는 파일).
+ * 구조: ① 상단 import(의존성) → ② 중단 run* 함수 정의(명령별 동작) → ③ 하단에서 commander로 명령을 등록하고
+ *       맨 끝 program.parse()가 argv를 해석해 실제 시동을 건다.
+ */
+import { Command } from 'commander';
+import { parseAll } from './parser.js';
+import { loadToken, saveToken, getOrCreateDeviceId, gistLogin, setHookInstalled, getLastSyncDate, saveLastSyncDate, clearLastSyncDate } from './auth.js';
+import { syncRecords, resetData } from './sync.js';
+import { installHook, uninstallHook } from './scheduler.js';
+import { promptFirstRun, promptDashboard, promptAdvanced, confirmReset, pauseForEnter, showError } from './ui.js';
+import { accent } from './gradient.js';
+import { localDateOf } from './lib/dates.js';
+import { claudeDirCandidates } from './parser.js';
+import { checkClaudeRetention, applyRetentionSetting, DEFAULT_CLEANUP_DAYS } from './lib/retention.js';
+import { refreshCache, getUpdateInfo } from './lib/update-check.js';
+import { runUpdate } from './lib/updater.js';
+import { confirm } from '@inquirer/prompts';
+import chalk from 'chalk';
+import { createRequire } from 'node:module';
+
+// API 서버 주소: 환경변수 우선, 없으면 운영 기본값 (dev는 TOKENPHAGE_API로 주입)
+const API_BASE = process.env.TOKENPHAGE_API ?? 'https://api.tokenphage.com';
+
+// package.json의 version 조회
+// createRequire는 import.meta.url 기준 상대경로를 해석하고, JSON import와 달리 Node 20에서도 경고 없이 동작한다.
+const { version } = createRequire(import.meta.url)('../package.json');
+
+/** 저장된 JWT를 반환한다. 없으면 로그인 안내를 출력하고 프로세스를 종료(exit 1)한다. */
+function requireToken() {
+  const token = loadToken();
+  if (!token) {
+    showError('Not authenticated', 'No saved credentials found.',
+      'Run `tokenphage login <github-username>` first.');
+    process.exit(1);
+  }
+  return token;
+}
+
+/** install-hook 명령 본체: 자동 sync 스케줄을 등록하고 설치 상태를 저장한 뒤 초기 sync까지 수행한다. */
+async function runInstallHook() {
+  requireToken();
+  const result = await installHook();
+  setHookInstalled(true, result);
+  console.log(`[OK] ${result.method} registered. Runs ${result.scheduleSpec}.`);
+  console.log(`     Log: ${result.logPath}`);
+  console.log(`     Artifact: ${result.artifactPath}`);
+  console.log('');
+  console.log('Running initial sync...');
+  await runSync();
+}
+
+/** uninstall-hook 명령 본체: 자동 sync 스케줄을 제거하고 설치 상태를 해제한다(스케줄이 없어도 정상 처리). */
+async function runUninstallHook() {
+  const result = await uninstallHook();
+  setHookInstalled(false);
+  console.log(result.removed ? '[OK] Removed' : '[OK] No schedule found');
+}
+
+/**
+ * gist 인증 직후 1회: Claude Code의 자동 삭제 위험을 실제 설정값과 함께 안내하고,
+ * 동의(Y) 시 무조건 99999로 설정한다. 이미 99999 이상이면 조용히 통과한다.
+ */
+async function promptRetentionSetup() {
+  const check = checkClaudeRetention(claudeDirCandidates());
+  if (!check.needed) return;
+
+  const printManualGuide = () => {
+    console.log(`    → To set it manually, add ${accent('"cleanupPeriodDays": 99999')} to ${accent(check.settingsPath)}`);
+  };
+
+  console.log('');
+  console.log(`  ${chalk.bold.red('⚠  Token history can be auto-deleted')}`);
+  console.log('');
+
+  // 설정 파일이 손상돼 현재값을 신뢰할 수 없으면 자동 설정 없이 수동 안내로 폴백.
+  if (check.corrupted) {
+    console.log(`     ${check.settingsPath} could not be parsed — skipping automatic setup.`);
+    printManualGuide();
+    return;
+  }
+
+  // 라벨을 색 없이 padEnd로 먼저 정렬한 뒤 값/강조에만 accent를 입힌다 (ANSI 코드가 폭 계산을 깨지 않도록).
+  const labelWidth = 'Current setting'.length;
+  const contIndent = ' '.repeat(3 + labelWidth + 3); // 라벨 다음 줄(연속 줄)을 값 위치에 맞추는 들여쓰기
+  const row = (label, value, highlightLabel = false) => {
+    const shown = highlightLabel ? accent(label) : label;
+    const pad = ' '.repeat(Math.max(0, labelWidth - label.length));
+    return `   ${shown}${pad} : ${value}`;
+  };
+
+  // 실제 cleanupPeriodDays 값 표시. 미설정이면 Claude Code 기본값(30) + (default) 표기.
+  const currentDesc = check.currentValue === null
+    ? `delete after ${accent(`${DEFAULT_CLEANUP_DAYS} days`)} ${chalk.dim('(default)')}`
+    : `delete after ${accent(`${check.currentValue} days`)}`;
+
+  console.log(row('Current setting', currentDesc));
+  console.log(row('Risk', 'deleted sessions are lost forever and'));
+  console.log(`${contIndent}go ${accent('MISSING')} from your token stats`);
+  console.log(row('Fix (Yes)', 'keep history forever — count every token', true));
+  console.log('');
+
+  let agreed;
+  try {
+    agreed = await confirm({
+      message: `${accent('Keep history forever?')} (updates ${accent(check.settingsPath)})`,
+      default: true,
+    });
+  } catch (err) {
+    if (err.name === 'ExitPromptError') process.exit(0); // Ctrl+C
+    throw err;
+  }
+
+  if (!agreed) {
+    printManualGuide();
+    return;
+  }
+
+  if (applyRetentionSetting(check.settingsPath)) {
+    console.log(`    ${chalk.green('✓')} Set ${accent('cleanupPeriodDays: 99999')} — history is now kept forever.`);
+  } else {
+    console.log(`    ${chalk.yellow('!')} Could not update the file automatically.`);
+    printManualGuide();
+  }
+}
+
+/** sync 명령 본체: 로컬 로그를 파싱(최초=전체 / 이후=증분)해 서버로 업로드하고, 마지막 sync 날짜를 갱신한다. */
+async function runSync() {
+  const token = requireToken();
+  const deviceId = getOrCreateDeviceId();
+  const today = localDateOf(new Date());
+
+  // 최초(lastSyncDate 없음)면 fromDate=null → 전체 히스토리 파싱.
+  // 이후엔 직전 sync일부터 오늘까지 증분만 파싱.
+  const lastSyncDate = getLastSyncDate();
+  const fromDate = lastSyncDate ?? null;
+
+  console.log(`Parsing local JSONL... (${fromDate ?? 'beginning'} ~ ${today})`);
+  const records = await parseAll(fromDate);
+  console.log(`${records.length} records aggregated (date×model)`);
+  if (records.length === 0) {
+    console.log('Nothing to sync.');
+    saveLastSyncDate(today);
+    return;
+  }
+
+  console.log('Uploading to server...');
+  await syncRecords(API_BASE, token, deviceId, records);
+  saveLastSyncDate(today);
+  console.log('Done! Badge will update shortly.');
+
+  // 이미 네트워크를 쓰는 지점이므로 여기서 npm 최신버전 캐시를 갱신한다(TTL 게이트 내장, 실패 무해).
+  // 04:00 자동 sync가 이 경로로 캐시를 채워, 다음 대시보드 진입 시 업데이트 배너가 뜬다.
+  await refreshCache(Date.now());
+}
+
+/**
+ * 고급 메뉴 본체: 현재는 'reset'(전체 초기화)만 처리한다.
+ * 확인 → 서버 데이터 삭제 → 로컬 워터마크 제거 → 전체 재-sync 순으로 진행하며, 각 단계 실패를 명확히 안내한다.
+ * @param {string} apiBase API 서버 base URL
+ * @param {object} cfg 현재 설정(JWT 포함)
+ */
+async function runAdvanced(apiBase, cfg) {
+  const sub = await promptAdvanced();
+  if (sub !== 'reset') return; // 'back' → 메시지 없이 즉시 대시보드 복귀
+  const confirmed = await confirmReset(cfg); // Ctrl+C는 ExitPromptError로 바깥 핸들러가 종료 처리
+  if (!confirmed) {
+    console.log(accent('  Reset cancelled.'));
+    await pauseForEnter();
+    return;
+  }
+  const token = cfg.token;
+  if (!token) {
+    showError('Not authenticated', 'No saved credentials found.',
+      'Authenticate again from the main menu.');
+    await pauseForEnter();
+    return;
+  }
+  // 1단계: 서버 데이터 삭제. 실패(쿨다운 429 등) 시 삭제된 데이터가 없으므로 그대로 종료.
+  try {
+    console.log('  Resetting server data...');
+    await resetData(apiBase, token);
+  } catch (err) {
+    showError('Reset failed', err.message, 'No data was deleted. Please try again later.');
+    await pauseForEnter();
+    return;
+  }
+  // 2단계: 로컬 워터마크 제거 후 전체 재-sync. 재-sync가 실패해도 서버 삭제는 이미 완료됐음을 명확히 안내.
+  clearLastSyncDate();
+  console.log(accent('  [OK] Server data reset.') + ' Re-syncing from scratch...');
+  try {
+    await runSync();
+    console.log(accent('  [OK] Reset complete — your data was rebuilt from scratch.'));
+  } catch (err) {
+    showError('Re-sync failed', err.message,
+      'Your server data was reset. Run `tokenphage sync` to rebuild your badge.');
+  }
+  await pauseForEnter();
+}
+
+// ========================================== START - CLI =========================================
+const program = new Command();
+program.name('tokenphage').description('AI token usage as a GitHub README badge — Tokenphage').version(version);
+
+// 기본 동작: 인자 없이 `tokenphage` 실행 시.
+// 미인증이면 인증 루프 → 보존 설정 → 초기 sync를 먼저 거치고, 그 뒤 대시보드 루프로 진입한다.
+program.action(async () => {
+  if (!process.stdin.isTTY) {
+    program.help();
+    return;
+  }
+  try {
+    if (!loadToken()) {
+      // 인증 루프: 실패해도 CLI를 죽이지 않고 알림 후 메뉴로 복귀(재시도/종료 선택 가능)
+      while (true) {
+        const action = await promptFirstRun();
+        if (action !== 'auth') return; // Exit 선택 → 종료
+        try {
+          const jwt = await gistLogin(API_BASE);
+          saveToken(jwt);
+          console.log('     → Saved to ~/.tokenphage/config.json');
+          break; // 인증 성공 → 루프 탈출
+        } catch (err) {
+          if (err.name === 'ExitPromptError') process.exit(0); // Ctrl+C
+          showError('Authentication failed', err.message,
+            'Make sure your Gist is public and owned by your GitHub account, then try again.');
+          await pauseForEnter(); // 사용자가 읽고 → 다시 메뉴로 복귀
+        }
+      }
+      // 인증 성공 → 보존 설정 안내 (첫 sync 전에 잡아야 이후 기록이 전부 보호됨)
+      await promptRetentionSetup();
+      // 초기 전체 sync (실패해도 죽지 않고 대시보드로 진행)
+      try {
+        console.log('');
+        console.log('Running initial full sync...');
+        await runSync();
+      } catch (err) {
+        if (err.name === 'ExitPromptError') process.exit(0);
+        showError('Initial sync failed', err.message,
+          'You are authenticated — you can run sync later from the menu.');
+        await pauseForEnter();
+      }
+    }
+
+    // 인증 이후 메뉴는 최신 설정이 필요하므로 여기서 동적 import (상단 정적 import과 별개)
+    const { loadConfig } = await import('./auth.js');
+    // 업데이트 캐시를 백그라운드로 갱신한다(await 안 함 → startup 지연 0). 결과는 다음 렌더에 반영된다.
+    refreshCache(Date.now()).catch(() => {});
+    // 대시보드 루프: 액션 수행 후 메인으로 복귀, Exit/Esc 에서만 종료
+    while (true) {
+      const cfg = loadConfig();
+      const action = await promptDashboard(cfg);
+      if (action === 'exit') break;
+      if (action === 'sync') await runSync();
+      else if (action === 'install-hook') await runInstallHook();
+      else if (action === 'uninstall-hook') await runUninstallHook();
+      else if (action === 'advanced') await runAdvanced(API_BASE, cfg);
+      else if (action === 'update') {
+        // 업데이트 성공 시 현재 프로세스는 여전히 구버전 코드 → 재실행 안내 후 종료.
+        const { hasUpdate, latest } = getUpdateInfo(version, cfg);
+        if (hasUpdate) {
+          const result = await runUpdate(latest);
+          await pauseForEnter();
+          if (result.updated) process.exit(0);
+        }
+      }
+    }
+  } catch (err) {
+    if (err.name === 'ExitPromptError') process.exit(0);
+    showError('Unexpected error', err.message);
+    process.exitCode = 1;
+  }
+});
+
+// ── 명시적 서브커맨드: `tokenphage <command>` 형태로 직접 호출하며, 위에서 정의한 run* 함수를 실행한다 ──
+
+// login [username]: Gist로 GitHub 소유권 증명 → JWT 저장 → 보존 설정 → 초기 sync. (대화형 터미널 필요)
+program.command('login [username]')
+  .description('Prove GitHub account ownership via a public Gist and save the JWT')
+  .action(async (username) => {
+    if (!process.stdin.isTTY) {
+      showError('Interactive terminal required', 'The login command needs an interactive terminal.');
+      process.exit(1);
+    }
+    try {
+      const token = await gistLogin(API_BASE, username);
+      saveToken(token);
+      console.log('     → Saved to ~/.tokenphage/config.json');
+      await promptRetentionSetup();
+      console.log('');
+      console.log('Running initial full sync...');
+      await runSync();
+    } catch (err) {
+      showError('Login failed', err.message);
+      process.exitCode = 1;
+    }
+  });
+
+// sync: 로컬 Claude/Codex 로그를 파싱해 서버로 업로드한다(배지 갱신). 미인증이면 안내 후 종료.
+program.command('sync')
+  .description('Sync local Claude Code token usage to the server')
+  .action(async () => {
+    try { await runSync(); }
+    catch (err) { showError('Sync failed', err.message); process.exitCode = 1; }
+  });
+
+// install-hook: 매일 04:00 자동 sync 스케줄을 OS별(macOS launchd / Windows Task Scheduler)로 등록한다.
+program.command('install-hook')
+  .description('Register a daily 04:00 auto-sync schedule (macOS launchd / Windows Task Scheduler)')
+  .action(async () => {
+    try { await runInstallHook(); }
+    catch (err) { showError('Install-hook failed', err.message); process.exitCode = 1; }
+  });
+
+// uninstall-hook: 자동 sync 스케줄을 제거한다(스케줄이 없어도 안전한 멱등 동작).
+program.command('uninstall-hook')
+  .description('Remove the auto-sync schedule (idempotent)')
+  .action(async () => {
+    try { await runUninstallHook(); }
+    catch (err) { showError('Uninstall-hook failed', err.message); process.exitCode = 1; }
+  });
+
+program.parse(); // argv를 해석해 알맞은 .action()으로 분기 — CLI 실제 시동 지점

package/src/lib/dates.js

@@ -0,0 +1,32 @@
+// 날짜 버킷팅 공용 헬퍼.
+// 트랜스크립트 타임스탬프(UTC)를 "사용자 체감 날짜"인 로컬 타임존 기준
+// lastSyncDate(로컬 기준)와 레코드 날짜의 기준을 일치시킨다.
+
+const formatterCache = new Map();
+
+/**
+ * 타임스탬프를 로컬(또는 지정 타임존) 날짜 문자열로 변환한다.
+ * @param {string|Date} ts ISO8601 문자열 또는 Date
+ * @param {string} [timeZone] IANA 타임존 (예: 'Asia/Seoul') — 미지정 시 시스템 로컬
+ * @returns {string|null} YYYY-MM-DD, 파싱 불가면 null
+ */
+export function localDateOf(ts, timeZone = undefined) {
+  if (!ts) return null;
+  const d = ts instanceof Date ? ts : new Date(ts);
+  if (Number.isNaN(d.getTime())) return null;
+
+  if (timeZone) {
+    let fmt = formatterCache.get(timeZone);
+    if (!fmt) {
+      // en-CA 로케일은 YYYY-MM-DD 형식을 보장한다.
+      fmt = new Intl.DateTimeFormat('en-CA', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' });
+      formatterCache.set(timeZone, fmt);
+    }
+    return fmt.format(d);
+  }
+
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, '0');
+  const day = String(d.getDate()).padStart(2, '0');
+  return `${y}-${m}-${day}`;
+}

package/src/lib/paths.js

@@ -0,0 +1,43 @@
+import { join, resolve } from 'path';
+
+// Claude 설정 디렉터리 후보를 우선순위 순으로 만든다.
+// 순서: 기본(~/.claude) → XDG($XDG_CONFIG_HOME/claude, 기본 ~/.config/claude) → 사용자 지정.
+
+function expandTilde(p, home) {
+  if (p === '~') return home;
+  if (p.startsWith('~/') || p.startsWith('~\\')) return join(home, p.slice(2));
+  return p;
+}
+
+/**
+ * Claude 설정 디렉터리 후보 목록을 우선순위 순으로 반환한다.
+ * @param {{ home: string, xdgConfigHome?: string, customPaths?: string[] }} opts
+ *   home: 사용자 홈, xdgConfigHome: $XDG_CONFIG_HOME, customPaths: config.json의 claudePaths
+ * @returns {string[]} normalize·중복 제거된 절대 경로 목록
+ */
+export function resolveClaudeDirs({ home, xdgConfigHome, customPaths } = {}) {
+  const xdgBase = typeof xdgConfigHome === 'string' && xdgConfigHome.trim()
+    ? xdgConfigHome
+    : join(home, '.config');
+
+  // 외부 입력(config.json) 검증: 문자열 배열만 인정, 그 외는 통째로 무시
+  const custom = Array.isArray(customPaths)
+    ? customPaths.filter((p) => typeof p === 'string' && p.trim())
+    : [];
+
+  const candidates = [
+    join(home, '.claude'),
+    join(xdgBase, 'claude'),
+    ...custom.map((p) => expandTilde(p.trim(), home)),
+  ];
+
+  const seen = new Set();
+  const dirs = [];
+  for (const candidate of candidates) {
+    const normalized = resolve(candidate);
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    dirs.push(normalized);
+  }
+  return dirs;
+}

package/src/lib/retention.js

@@ -0,0 +1,67 @@
+import { existsSync, readFileSync, writeFileSync, renameSync } from 'fs';
+import { join } from 'path';
+
+// Claude Code의 cleanupPeriodDays(트랜스크립트 보존 기간) 검사·설정.
+// 규칙은 하나: 99999 이상이면 통과, 아니면 동의를 받아 무조건 99999로 설정한다.
+// (0=off는 Claude Code가 거부하므로 큰 값으로 무력화하는 방식)
+// 손상된 설정 파일은 절대 건드리지 않는다.
+
+export const FOREVER_DAYS = 99999;
+
+// Claude Code가 cleanupPeriodDays 미설정 시 적용하는 기본 보존 일수.
+// 미설정 사용자에게 "실제로 무슨 일이 일어나는지"를 보여주기 위한 표시용 상수.
+export const DEFAULT_CLEANUP_DAYS = 30;
+
+// 후보 중 실제 사용 중인 설정 디렉터리: projects/가 존재하는 첫 dir, 없으면 첫 후보.
+function pickActiveClaudeDir(claudeDirs) {
+  return claudeDirs.find((dir) => existsSync(join(dir, 'projects'))) ?? claudeDirs[0];
+}
+
+/**
+ * 사용 중인 Claude 설정 디렉터리의 cleanupPeriodDays가 99999 이상인지 검사한다.
+ * @param {string[]} claudeDirs resolveClaudeDirs() 결과 (우선순위 순)
+ * @returns {{ needed: boolean, settingsPath: string, corrupted: boolean, currentValue: number | null }}
+ *   needed: 설정이 필요한지(99999 미만/미설정/손상), corrupted: settings.json 파싱 실패 여부,
+ *   currentValue: 현재 설정된 cleanupPeriodDays 숫자값 (미설정·파일없음·손상이면 null — 호출부가 기본값으로 표시)
+ */
+export function checkClaudeRetention(claudeDirs) {
+  const settingsPath = join(pickActiveClaudeDir(claudeDirs), 'settings.json');
+
+  if (!existsSync(settingsPath)) {
+    return { needed: true, settingsPath, corrupted: false, currentValue: null };
+  }
+  try {
+    const value = JSON.parse(readFileSync(settingsPath, 'utf8')).cleanupPeriodDays;
+    const currentValue = typeof value === 'number' ? value : null;
+    const isForever = currentValue !== null && currentValue >= FOREVER_DAYS;
+    return { needed: !isForever, settingsPath, corrupted: false, currentValue };
+  } catch {
+    return { needed: true, settingsPath, corrupted: true, currentValue: null };
+  }
+}
+
+/**
+ * settings.json의 cleanupPeriodDays를 무조건 99999로 설정한다 (다른 필드 보존, 원자 쓰기).
+ * @param {string} settingsPath checkClaudeRetention()이 돌려준 settings.json 경로
+ * @returns {boolean} 성공 여부 — 손상 JSON이면 수정하지 않고 false
+ */
+export function applyRetentionSetting(settingsPath) {
+  let config = {};
+  if (existsSync(settingsPath)) {
+    try {
+      config = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    } catch {
+      return false; // 손상 파일은 건드리지 않는다
+    }
+  }
+
+  try {
+    const next = { ...config, cleanupPeriodDays: FOREVER_DAYS };
+    const tmpPath = settingsPath + '.tmp';
+    writeFileSync(tmpPath, JSON.stringify(next, null, 2) + '\n');
+    renameSync(tmpPath, settingsPath); // 같은 디렉터리 내 rename = 원자적 교체
+    return true;
+  } catch {
+    return false; // 권한 문제 등 — 호출부가 수동 안내로 폴백
+  }
+}

package/src/lib/update-check.js

@@ -0,0 +1,104 @@
+/**
+ * CLI 업데이트 검사: npm 레지스트리에서 최신버전을 조회해 config.json에 캐시하고,
+ * 현재 버전과 비교해 업데이트 여부를 판정한다.
+ *
+ * 설계 원칙
+ *  - 화면(메인 대시보드)은 캐시(getUpdateInfo)만 읽어 즉시 렌더 → startup 지연 0.
+ *  - 네트워크 조회(refreshCache)는 백그라운드/sync 시점에 돌아 캐시를 채우고, 결과는 "다음 렌더"에 반영된다.
+ *  - 어떤 실패(네트워크·404·파싱·옵트아웃)도 조용히 흘려보내 본 기능(대시보드)을 절대 막지 않는다.
+ */
+import { loadConfig, saveUpdateCache } from '../auth.js';
+
+// 배포 패키지명 — 레지스트리 URL과 `npm i -g` 대상에서 공유한다.
+export const PACKAGE_NAME = 'tokenphage';
+// npm 레지스트리 latest 매니페스트(공개·무인증). { "version": "", ... } 반환, 미배포면 404.
+export const REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24h TTL — 하루 1회만 조회
+const FETCH_TIMEOUT_MS = 2500;                 // 레지스트리 지연이 sync를 끌지 않도록 상한
+
+/**
+ * CalVer "YYYY.M.PATCH" 두 버전을 숫자 3파트로 비교한다.
+ * @returns {-1|0|1} a<b → -1, a==b → 0, a>b → 1. 어느 한쪽이라도 비숫자(dev 등)면 0(=차이 없음)으로 안전 폴백.
+ */
+export function compareVersion(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  // CalVer는 정확히 3파트여야 한다. 형식이 어긋나면(2파트/4파트/dev 등) 비교 불가로 보고 0(=업데이트 없음) 폴백.
+  if (pa.length !== 3 || pb.length !== 3) return 0;
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i];
+    const y = pb[i];
+    if (Number.isNaN(x) || Number.isNaN(y)) return 0; // 비CalVer → 비교 불가 → 업데이트 없음
+    if (x > y) return 1;
+    if (x < y) return -1;
+  }
+  return 0;
+}
+
+/**
+ * 마지막 조회 이후 TTL(24h)이 지났는지 판정한다. now는 인자로 주입해 테스트 결정성을 확보한다.
+ * @param {string|null} lastUpdateCheck 마지막 조회 ISO 시각 (없으면 null)
+ * @param {number} now 현재 epoch ms
+ * @returns {boolean} 조회가 필요하면 true
+ */
+export function shouldCheck(lastUpdateCheck, now) {
+  if (!lastUpdateCheck) return true;
+  const last = Date.parse(lastUpdateCheck);
+  if (Number.isNaN(last)) return true; // 손상된 시각 → 재조회
+  return now - last >= CHECK_INTERVAL_MS;
+}
+
+/** 업데이트 알림을 끄는 환경인지. 옵트아웃 env 또는 dev(TOKENPHAGE_API 세팅)면 조회·표시 모두 스킵. */
+export function isUpdateNotifierDisabled() {
+  return !!process.env.TOKENPHAGE_NO_UPDATE_NOTIFIER || !!process.env.TOKENPHAGE_API;
+}
+
+/**
+ * 캐시(cfg.latestVersion)와 현재 버전을 비교해 업데이트 정보를 반환한다. 네트워크를 쓰지 않는 동기 함수.
+ * @param {string} currentVersion 현재 설치 버전(package.json)
+ * @param {object} cfg loadConfig() 결과(또는 동등한 객체)
+ * @returns {{hasUpdate:boolean, latest?:string, current?:string}}
+ */
+export function getUpdateInfo(currentVersion, cfg) {
+  if (isUpdateNotifierDisabled()) return { hasUpdate: false };
+  const latest = cfg?.latestVersion;
+  if (!latest) return { hasUpdate: false };
+  if (compareVersion(latest, currentVersion) > 0) {
+    return { hasUpdate: true, latest, current: currentVersion };
+  }
+  return { hasUpdate: false };
+}
+
+/** npm 레지스트리에서 latest 버전 문자열을 조회한다. 실패(타임아웃·404·파싱)는 모두 null. */
+async function fetchLatestFromNpm() {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(REGISTRY_URL, { signal: controller.signal });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return typeof body?.version === 'string' ? body.version : null;
+  } catch {
+    return null; // 네트워크 단절·abort·비JSON 등 — 조용히 무시
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * TTL이 지났으면 npm 최신버전을 조회해 config 캐시를 갱신한다. 절대 throw하지 않는다.
+ * @param {number} now 현재 epoch ms (Date.now()를 주입)
+ */
+export async function refreshCache(now) {
+  try {
+    if (isUpdateNotifierDisabled()) return;
+    const cfg = loadConfig();
+    if (!shouldCheck(cfg.lastUpdateCheck, now)) return;
+    const latest = await fetchLatestFromNpm();
+    if (!latest) return;
+    saveUpdateCache(latest, new Date(now).toISOString());
+  } catch {
+    // 캐시 갱신 실패는 무해 — 다음 기회에 재시도한다.
+  }
+}

package/src/lib/updater.js

@@ -0,0 +1,86 @@
+/**
+ * 1-클릭 업데이트: 전역(npm i -g) 설치인지 감지해, 전역이면 최신버전을 설치하고,
+ * 그 외(npx/로컬 의존성/git clone)면 정확한 수동 명령을 안내한다.
+ *
+ * 현재 프로세스는 설치 직후에도 여전히 "구버전 코드"이므로(핫스왑 불가),
+ * 성공 시 재실행을 안내하고 호출부(index.js)에서 프로세스를 종료한다.
+ */
+import { spawn, execFileSync } from 'child_process';
+import { realpathSync } from 'fs';
+import chalk from 'chalk';
+import { accent } from '../gradient.js';
+import { PACKAGE_NAME } from './update-check.js';
+
+const isWin = process.platform === 'win32';
+// Windows는 spawn('npm')이 ENOENT → npm.cmd를 쓴다. 또 최신 Node는 보안 패치(CVE-2024-27980) 이후
+// .cmd 실행에 shell:true를 요구한다. 인자는 전부 고정 리터럴(아래 PACKAGE_NAME 상수)이라 인젝션 표면이 없다.
+const npmCmd = isWin ? 'npm.cmd' : 'npm';
+const MANUAL_CMD = `npm install -g ${PACKAGE_NAME}@latest`;
+
+/** npm 전역 설치 루트(`npm root -g`)를 반환한다. 실패하면 null. */
+function globalRoot() {
+  try {
+    return execFileSync(npmCmd, ['root', '-g'], { encoding: 'utf8', shell: isWin }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/** 현재 실행 중인 CLI가 전역 npm 설치(.../lib/node_modules/...)인지 realpath prefix 매칭으로 판정한다. */
+function isGlobalInstall() {
+  try {
+    const script = realpathSync(process.argv[1]);
+    const root = globalRoot();
+    return !!root && script.startsWith(realpathSync(root));
+  } catch {
+    return false; // 불확실하면 전역 아님으로 간주 → 수동 안내(잘못된 npm i -g 방지)
+  }
+}
+
+/** `npm install -g <pkg>@latest`를 출력 스트리밍으로 실행한다. {ok, code?, err?} 반환. */
+function npmInstallGlobal() {
+  return new Promise((resolve) => {
+    const child = spawn(npmCmd, ['install', '-g', `${PACKAGE_NAME}@latest`], {
+      stdio: 'inherit',
+      shell: isWin,
+    });
+    child.on('error', (err) => resolve({ ok: false, err }));      // ENOENT 등 실행 자체 실패
+    child.on('close', (code) => resolve({ ok: code === 0, code })); // 종료 코드로 성공 판정
+  });
+}
+
+/** 정확한 수동 업데이트 명령을 강조색으로 출력한다. */
+function printManual() {
+  console.log(accent(`  → ${MANUAL_CMD}`));
+}
+
+/**
+ * 업데이트를 수행한다.
+ * @param {string} latest 설치 대상 최신버전(표시용)
+ * @returns {Promise<{updated:boolean}>} updated=true면 호출부가 재실행 안내 후 프로세스를 종료해야 한다.
+ */
+export async function runUpdate(latest) {
+  // 전역 설치가 아니면 자동 업데이트가 위험/무의미 → 수동 명령만 안내.
+  if (!isGlobalInstall()) {
+    console.log(chalk.gray('  Not a global npm install — update manually:'));
+    printManual();
+    return { updated: false };
+  }
+
+  console.log(accent(`  Updating to v${latest}...`));
+  const result = await npmInstallGlobal();
+
+  if (result.ok) {
+    console.log(accent(`  ✓ Updated. Restart tokenphage to use v${latest}.`));
+    return { updated: true };
+  }
+
+  // 실행 실패(npm 없음) vs 종료코드 실패(권한 등)를 구분해 안내.
+  if (result.err) {
+    console.log(chalk.yellow('  npm was not found or failed to launch.'));
+  } else {
+    console.log(chalk.yellow('  Update failed (permission?). Try again with the right permissions, or update manually:'));
+  }
+  printManual();
+  return { updated: false };
+}