tokenphage 2026.7.0-BETA → 2026.7.2-BETA

package/README.md

@@ -1,26 +1,70 @@
 # TokenPhage CLI
 
-> AI 토큰 사용량을 GitHub README 배지로 보여주는 CLI.
+![CLI](https://img.shields.io/badge/CLI-Node.js%20ESM-5EEAD4?style=flat-square)
+![License](https://img.shields.io/badge/license-MIT-555?style=flat-square)
+
+> 먹어치운 토큰, 이젠 README에 기록하세요!
 
 Claude Code와 Codex의 토큰 사용량을 모아 GitHub README에 붙일 수 있는 배지로 만들어 줍니다.
 
 ---
 
-## 요구 사항
+## 📋 요구 사항
 
 - **Node.js 20.17 이상**
 - macOS 또는 Windows (자동 동기화 사용 시)
 - GitHub 계정
 
-## 설치
+## 🖼️ 이런 배지가 만들어져요
+
+GitHub README(이미지를 붙일 수 있는 곳이면 어디든)에 아래 한 줄만 넣으면 됩니다. `kobenlys`를 본인 GitHub 아이디로 바꾸세요.
+
+```markdown
+[![TokenPhage](https://api.tokenphage.com/badge/kobenlys)](https://github.com/TOKENPHAGE/tokenphage-api)
+```
+
+**결과 ↓**
+
+<table>
+  <tr>
+    <td align="center"><strong>gpu · dark</strong></td>
+    <td align="center"><strong>claude · light</strong></td>
+  </tr>
+  <tr>
+    <td align="center">
+      <a href="https://github.com/TOKENPHAGE/tokenphage-api"><img src="https://api.tokenphage.com/badge/kobenlys?theme=gpu&amp;mode=dark" alt="TokenPhage gpu dark 배지"></a><br/>
+      <code>https://api.tokenphage.com/badge/kobenlys?theme=gpu&amp;mode=dark</code>
+    </td>
+    <td align="center">
+      <a href="https://github.com/TOKENPHAGE/tokenphage-api"><img src="https://api.tokenphage.com/badge/kobenlys?theme=claude&amp;mode=light" alt="TokenPhage claude light 배지"></a><br/>
+      <code>https://api.tokenphage.com/badge/kobenlys?theme=claude&amp;mode=light</code>
+    </td>
+  </tr>
+</table>
+
+> 🎨 URL 뒤에 옵션을 붙일 수 있어요 — 테마 `?theme=gpu`(기본) 또는 `?theme=claude`, 색상 `?mode=light`(기본) 또는 `?mode=dark`.
+
+## 📦 설치
 
 ```bash
-npm install -g tokenphage
+npm install -g tokenphage@latest
 ```
 
 설치 후 `tokenphage` 명령을 쓸 수 있습니다.
 
-## 빠른 시작
+### ⬆️ 업데이트
+
+대시보드를 열면 새 버전이 있는지 확인합니다. 새 버전이 확인되면 대시보드 맨 위에 안내 배너가 뜨고, 메뉴에 **⬆ Update to …** 항목이 추가됩니다. 이 항목을 고르면 최신 버전이 자동으로 설치됩니다(전역 설치가 아니면 정확한 수동 명령을 안내).
+
+직접 올리고 싶다면 언제든 아래 명령을 실행하면 됩니다.
+
+```bash
+npm install -g tokenphage@latest
+```
+
+> 업데이트 알림을 끄려면 `TOKENPHAGE_NO_UPDATE_NOTIFIER=1` 환경 변수를 설정하세요.
+
+## 🚀 빠른 시작
 
 ```bash
 tokenphage                       # 대화형 화면 실행 (처음이면 로그인부터 안내)
@@ -31,23 +75,7 @@ tokenphage install-hook          # 매일 04:00 자동 동기화 켜기
 
 ---
 
-## 명령어
-
-| 명령 | 하는 일 |
-|------|---------|
-| `tokenphage` | 대화형 화면(메뉴)을 엽니다. 아래 [대화형 사용법](#대화형-사용법) 참고 |
-| `tokenphage login [github-id]` | GitHub 계정을 인증하고 로그인합니다. 아이디를 함께 적으면 입력 단계를 건너뜁니다 |
-| `tokenphage sync` | 지금 바로 토큰 사용량을 동기화합니다. 잠시 뒤 배지가 갱신됩니다 |
-| `tokenphage install-hook` | 매일 **오전 4시**에 자동으로 동기화되도록 설정합니다 |
-| `tokenphage uninstall-hook` | 자동 동기화를 끕니다 |
-| `tokenphage --version` | 버전을 봅니다 |
-| `tokenphage --help` | 도움말을 봅니다 |
-
-> `login`은 화면 입력이 필요해 일반 터미널에서 실행해야 합니다.
-
----
-
-## 대화형 사용법
+## 💻 대화형 사용법
 
 `tokenphage`를 그냥 실행하면 메뉴가 뜹니다. **↑/↓로 이동, Enter로 선택, Esc로 종료**합니다.
 
@@ -69,6 +97,7 @@ tokenphage install-hook          # 매일 04:00 자동 동기화 켜기
     Advanced settings
     Exit
 ```
+- **⬆ Update to …** — 새 버전이 있을 때만 맨 위에 나타나며, 고르면 최신 버전으로 자동 업데이트
 - **Sync now** — 지금 바로 동기화
 - **Enable / Disable auto-sync** — 자동 동기화 켜기/끄기 (현재 상태에 맞춰 표시)
 - **Advanced settings** — 데이터 초기화 등
@@ -83,7 +112,7 @@ tokenphage install-hook          # 매일 04:00 자동 동기화 켜기
 
 ---
 
-## 로그인 (Gist 인증)
+## 🔐 로그인 (Gist 인증)
 
 비밀번호 없이, **본인 GitHub 계정으로 공개 Gist를 만들 수 있다는 점**으로 계정을 인증합니다.
 
@@ -96,7 +125,23 @@ tokenphage install-hook          # 매일 04:00 자동 동기화 켜기
 
 ---
 
-## 자동 동기화
+## ⌨️ 명령어
+
+| 명령 | 하는 일 |
+|------|---------|
+| `tokenphage` | 대화형 화면(메뉴)을 엽니다. [대화형 사용법](#-대화형-사용법) 참고 |
+| `tokenphage login [github-id]` | GitHub 계정을 인증하고 로그인합니다. 아이디를 함께 적으면 입력 단계를 건너뜁니다 |
+| `tokenphage sync` | 지금 바로 토큰 사용량을 동기화합니다. 잠시 뒤 배지가 갱신됩니다 |
+| `tokenphage install-hook` | 매일 자동으로 동기화되도록 설정합니다 (시간·상세는 자동 동기화 절 참고) |
+| `tokenphage uninstall-hook` | 자동 동기화를 끕니다 |
+| `tokenphage --version` | 버전을 봅니다 |
+| `tokenphage --help` | 도움말을 봅니다 |
+
+> `login`은 화면 입력이 필요해 일반 터미널에서 실행해야 합니다.
+
+---
+
+## ⏰ 자동 동기화
 
 `install-hook`을 켜면 매일 **오전 4시**에 자동으로 동기화됩니다(macOS·Windows). 컴퓨터를 거의 안 쓰는 시간대라 작업을 방해하지 않습니다.
 
@@ -110,24 +155,44 @@ tokenphage install-hook          # 매일 04:00 자동 동기화 켜기
 
 ---
 
-## 저장되는 곳
+## ⚙️ config.json 설정
 
-로그인 정보와 설정은 `~/.tokenphage/` 폴더에 저장됩니다. 로그아웃하거나 초기화하려면 이 폴더를 지우면 됩니다.
+로그인 정보와 설정은 `~/.tokenphage/config.json`에 저장됩니다. 여기에는 로그인 토큰(JWT), **기기 식별자(deviceId)**, 마지막 동기화 날짜, 자동 동기화 설정이 들어 있습니다.
 
----
+> ⚠️ **이 폴더나 `config.json`을 임의로 지우지 마세요.** `deviceId`가 사라지면 아래처럼 토큰 집계에 노이즈가 생길 수 있습니다.
+
+### 🗑️ 만약 지워졌다면 (노이즈가 생기는 이유)
+
+`config.json`이 사라지면(폴더 삭제·재설치·다른 기기 등) 이런 일이 벌어집니다.
 
-## 토큰이 누락되지 않게 하기
+1. 로그인 토큰이 없어져 **다시 Gist 인증**을 해야 합니다.
+2. 재인증하면 **새 `deviceId`가 발급**됩니다 (기존 것은 복구 불가).
+3. 마지막 동기화 기록도 사라져, 다음 `sync`가 **전체 히스토리를 처음부터 다시 업로드**합니다.
+4. 서버는 같은 사용량이라도 `deviceId`가 다르면 **별도 행으로 저장**하고, 배지의 누적 토큰은 **모든 `deviceId`를 합산**합니다. → 같은 기록이 옛 `deviceId` + 새 `deviceId`로 **이중 집계되어 누적 토큰이 실제보다 부풀려집니다.** (다른 PC에서 각각 동기화한 것과 같은 노이즈)
 
-Claude Code는 오래된 세션 기록을 자동으로 지울 수 있고, 지워진 기록의 토큰은 다시 집계되지 않습니다. 그래서 로그인 직후 CLI가 **"기록을 계속 보관할지"** 물어봅니다. **Yes**로 두면 이후 모든 토큰이 빠짐없이 집계됩니다.
+### ✅ 노이즈를 없애는 법 — 전체 초기화(Reset)
+
+1. `tokenphage` 실행 → 필요하면 먼저 재로그인(Gist 인증) → **Advanced settings → Reset all data**
+2. 확인을 위해 본인 GitHub 아이디를 입력하면, 서버에 쌓인 **내 토큰 사용량 전체(노이즈 포함)를 삭제**한 뒤 곧바로 처음부터 다시 동기화합니다.
+3. 그 결과 **현재 기기(단일 `deviceId`) 기준의 깨끗한 누적치**로 복구됩니다.
+
+> ℹ️ Reset은 **서버 데이터만** 지우며 로컬 Claude 기록은 건드리지 않습니다. 남용 방지를 위해 **24시간에 한 번**만 가능합니다.
 
 ---
 
-## 문제 해결
+## ⚠️ 유의사항
+
+### 🧹 토큰이 누락되지 않게 하기
+
+**Claude Code는 오래된 세션 기록(트랜스크립트)을 자동으로 삭제합니다.** 삭제된 기록의 토큰은 다시 집계할 수 없어, 그대로 두면 누적량에서 빠져 버립니다.
+
+- 보존 기간은 Claude Code의 **`cleanupPeriodDays`** 설정으로 정해집니다. **따로 지정하지 않으면 기본 30일**이라, 30일이 지난 세션은 사라집니다.
+- 그래서 **로그인 직후**(보존 기간이 넉넉하지 않을 때) CLI가 한 번 **"기록을 계속 보관할지"**를 물어봅니다.
+- **Yes**를 고르면 `~/.claude/settings.json`의 `cleanupPeriodDays`를 **`99999`(사실상 영구)**로 바꿔, 이후 모든 토큰이 빠짐없이 집계됩니다. (이미 충분히 큰 값이면 그대로 둡니다)
+- 설정 파일이 손상돼 있으면 **건드리지 않고**, 수동으로 넣는 방법을 안내합니다.
 
-| 증상 | 해결 |
-|------|------|
-| `Not authenticated` 라고 나옴 | 먼저 `tokenphage login <github-id>` 로 로그인 |
-| `login` 이 바로 종료됨 | 일반 터미널(입력 가능한 창)에서 실행 |
-| 자동 동기화 설정 중 권한 거부 | macOS: 자동화 권한 허용 / Windows: 관리자 터미널에서 재실행 |
-| 자동 동기화가 안 도는 것 같음 | `~/.tokenphage/logs/sync.log` 확인 |
-| 토큰이 누락됨 | 로그인 직후 안내된 "기록 보관" 설정을 켰는지 확인 |
+> 💡 **직접 설정하고 싶다면** `~/.claude/settings.json`에 아래 한 줄을 추가하세요.
+>
+> ```json
+> { "cleanupPeriodDays": 99999 }
+> ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenphage",
-  "version": "2026.7.0-BETA",
+  "version": "2026.7.2-BETA",
   "description": "AI 토큰 사용량 GitHub README 뱃지",
   "author": "kobenlys <kobenlys@gmail.com>",
   "license": "MIT",

package/src/auth.js

@@ -1,23 +1,43 @@
-import { readFileSync, writeFileSync, mkdirSync, chmodSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync, chmodSync, renameSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 import { randomUUID } from 'crypto';
+import { normalizeConfig } from './lib/config-schema.js';
+import { localDateOf } from './lib/dates.js';
 
 // 로컬 설정 파일 경로: ~/.tokenphage/config.json (JWT·deviceId·sync 상태 보관)
 const CONFIG_DIR = join(homedir(), '.tokenphage');
 const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
 
-/** config.json을 읽어 객체로 반환한다. 파일이 없거나 손상됐으면 빈 객체. */
+/** 손상된 config.json을 .corrupt-{시각}으로 rename해 보존한다(원본 유지 + 재손상 방지). */
+function quarantineCorruptConfig() {
+  try {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    renameSync(CONFIG_PATH, `${CONFIG_PATH}.corrupt-${stamp}`);
+  } catch { /* 격리 실패는 무시 */ }
+}
+
+/** config.json을 읽어 정규화된 객체로 반환한다. 파일 없음/손상 시 빈 객체(손상은 격리 후). throw하지 않는다. */
 export function loadConfig() {
-  try { return JSON.parse(readFileSync(CONFIG_PATH, 'utf8')); }
-  catch { return {}; }
+  let raw;
+  try { raw = readFileSync(CONFIG_PATH, 'utf8'); }
+  catch (err) {
+    if (err.code === 'ENOENT') return {}; // 파일 없음
+    return {};                            // 기타 읽기 실패
+  }
+  let parsed;
+  try { parsed = JSON.parse(raw); }
+  catch { quarantineCorruptConfig(); return {}; } // 파싱 실패 → 격리
+  return normalizeConfig(parsed, localDateOf(new Date()));
 }
 
-/** config 객체를 config.json에 저장한다. JWT가 담기므로 소유자 전용(0600) 권한으로 기록한다. */
+/** config를 config.json에 원자적으로 저장한다(임시 파일 기록 후 rename, 소유자 전용 0600). */
 export function saveConfig(cfg) {
   mkdirSync(CONFIG_DIR, { recursive: true });
-  writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2), { mode: 0o600 });
-  try { chmodSync(CONFIG_PATH, 0o600); } catch { /* Windows는 chmod 미지원 — 무시 */ }
+  const tmp = `${CONFIG_PATH}.tmp-${process.pid}`; // 같은 디렉터리라 rename 원자적
+  writeFileSync(tmp, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+  try { chmodSync(tmp, 0o600); } catch { /* Windows 미지원 */ }
+  renameSync(tmp, CONFIG_PATH);
 }
 
 /** 저장된 JWT를 반환한다. 없으면 null. */
@@ -73,17 +93,6 @@ export function clearLastSyncDate() {
   saveConfig(rest);
 }
 
-/** 업데이트 캐시(npm 최신버전·마지막 조회시각)를 반환한다. 없으면 각각 null. */
-export function getUpdateCache() {
-  const cfg = loadConfig();
-  return { latestVersion: cfg.latestVersion ?? null, lastUpdateCheck: cfg.lastUpdateCheck ?? null };
-}
-
-/** npm 최신버전과 조회시각(ISO)을 다른 설정을 보존한 채 갱신 저장한다. */
-export function saveUpdateCache(latestVersion, lastUpdateCheck) {
-  saveConfig({ ...loadConfig(), latestVersion, lastUpdateCheck });
-}
-
 // Gist 소유권 검증용 파일명 — 사용자가 이 이름으로 Gist를 만들어야 한다.
 export const VERIFICATION_FILE = 'tokenphage.txt';
 

package/src/index.js

@@ -14,7 +14,7 @@ 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 { checkLatestVersion, getUpdateInfo } from './lib/update-check.js';
 import { runUpdate } from './lib/updater.js';
 import { confirm } from '@inquirer/prompts';
 import chalk from 'chalk';
@@ -149,10 +149,6 @@ async function runSync() {
   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());
 }
 
 /**
@@ -245,12 +241,12 @@ program.action(async () => {
 
     // 인증 이후 메뉴는 최신 설정이 필요하므로 여기서 동적 import (상단 정적 import과 별개)
     const { loadConfig } = await import('./auth.js');
-    // 업데이트 캐시를 백그라운드로 갱신한다(await 안 함 → startup 지연 0). 결과는 다음 렌더에 반영된다.
-    refreshCache(Date.now()).catch(() => {});
+    // TUI 진입 시 npm 최신버전을 1회 조회(짧은 타임아웃). 세션 동안 재사용해 배너/메뉴에 반영한다.
+    const latest = await checkLatestVersion();
     // 대시보드 루프: 액션 수행 후 메인으로 복귀, Exit/Esc 에서만 종료
     while (true) {
       const cfg = loadConfig();
-      const action = await promptDashboard(cfg);
+      const action = await promptDashboard(cfg, latest);
       if (action === 'exit') break;
       if (action === 'sync') await runSync();
       else if (action === 'install-hook') await runInstallHook();
@@ -258,7 +254,7 @@ program.action(async () => {
       else if (action === 'advanced') await runAdvanced(API_BASE, cfg);
       else if (action === 'update') {
         // 업데이트 성공 시 현재 프로세스는 여전히 구버전 코드 → 재실행 안내 후 종료.
-        const { hasUpdate, latest } = getUpdateInfo(version, cfg);
+        const { hasUpdate } = getUpdateInfo(version, latest);
         if (hasUpdate) {
           const result = await runUpdate(latest);
           await pauseForEnter();
@@ -307,7 +303,7 @@ program.command('sync')
 
 // 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)')
+  .description('Register a daily 04:00 auto-sync schedule (macOS launchd / Windows Task Scheduler / Linux cron)')
   .action(async () => {
     try { await runInstallHook(); }
     catch (err) { showError('Install-hook failed', err.message); process.exitCode = 1; }

package/src/lib/config-schema.js

@@ -0,0 +1,93 @@
+/**
+ * config.json 스키마 검증·정규화·마이그레이션. 순수 함수(fs·네트워크 없음).
+ * 이상 필드는 제거하고 유효·미지 필드는 보존한다. 형태/타입만 검증하며 JWT 서명은 검증하지 않는다.
+ */
+
+// config.json 스키마 버전. breaking 변경 시 +1 하고 migrateConfig에 단계를 추가한다.
+export const CURRENT_CONFIG_VERSION = 1;
+
+const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+const YMD_RE = /^\d{4}-\d{2}-\d{2}$/;
+const JWT_SEGMENT_RE = /^[A-Za-z0-9_-]+$/;
+
+/** JWT 형태(base64url 3세그먼트)인지 검사한다. 서명은 검증하지 않는다. */
+export function isJwtShape(v) {
+  if (typeof v !== 'string') return false;
+  const parts = v.split('.');
+  return parts.length === 3 && parts.every((p) => p.length > 0 && JWT_SEGMENT_RE.test(p));
+}
+
+/** UUID 형식(서버 SyncRequest 패턴과 동일)인지 검사한다. */
+export function isUuid(v) {
+  return typeof v === 'string' && UUID_RE.test(v);
+}
+
+/**
+ * YYYY-MM-DD이고 실제 존재하는 날짜이며 today 이전인지 검사한다.
+ * @param {string} today 미래 금지 기준 날짜(YYYY-MM-DD)
+ */
+export function isYmdDate(v, today) {
+  if (typeof v !== 'string' || !YMD_RE.test(v)) return false;
+  const [y, m, d] = v.split('-').map(Number);
+  // 롤오버(예: 2/30 → 3/2) 차단: 컴포넌트 재구성 후 일치하는 날짜만 통과.
+  const dt = new Date(Date.UTC(y, m - 1, d));
+  const real = dt.getUTCFullYear() === y && dt.getUTCMonth() === m - 1 && dt.getUTCDate() === d;
+  if (!real) return false;
+  // 미래 금지(동일 포맷이라 문자열 비교로 충분). today 미제공 시 생략.
+  if (typeof today === 'string' && YMD_RE.test(today) && v > today) return false;
+  return true;
+}
+
+/** Date.parse로 해석 가능한 ISO 시각 문자열인지 검사한다. */
+export function isIsoDate(v) {
+  return typeof v === 'string' && !Number.isNaN(Date.parse(v));
+}
+
+/** 문자열만 담긴 배열인지 검사한다. */
+export function isStringArray(v) {
+  return Array.isArray(v) && v.every((x) => typeof x === 'string');
+}
+
+/**
+ * config를 현재 스키마 버전으로 마이그레이트한다. 순수·멱등.
+ * @param {object} raw 파싱된 config
+ * @returns {object} 마이그레이트된 새 객체
+ */
+export function migrateConfig(raw) {
+  const version = Number.isInteger(raw.configVersion) ? raw.configVersion : 0;
+  if (version > CURRENT_CONFIG_VERSION) return { ...raw }; // 미래 버전은 보존
+  let out = { ...raw };
+  if (version < 1) out = { ...out, configVersion: 1 }; // 0 → 1: 버전 스탬프만
+  return out;
+}
+
+/**
+ * 파싱된 config를 검증·정규화한다. 이상 필드는 제거하고 유효·미지 필드는 보존한다.
+ * @param {*} raw JSON.parse 결과
+ * @param {string} today lastSyncDate 미래 검사 기준(YYYY-MM-DD)
+ * @returns {object} 정규화된 config
+ */
+export function normalizeConfig(raw, today) {
+  if (raw == null || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { configVersion: CURRENT_CONFIG_VERSION };
+  }
+  const migrated = migrateConfig(raw);
+  // 미래 버전은 검증 없이 그대로 반환한다.
+  if (Number.isInteger(migrated.configVersion) && migrated.configVersion > CURRENT_CONFIG_VERSION) {
+    return migrated;
+  }
+
+  const out = { ...migrated }; // 미지 필드 보존
+  const dropIf = (key, ok) => { if (key in out && !ok(out[key])) delete out[key]; };
+
+  dropIf('token', isJwtShape);
+  dropIf('deviceId', isUuid);                         // 없으면 getOrCreateDeviceId가 재발급
+  dropIf('lastSyncDate', (v) => isYmdDate(v, today)); // 없으면 전체 재파싱
+  dropIf('hookInstalledAt', isIsoDate);
+  dropIf('hookInstalled', (v) => typeof v === 'boolean');
+  dropIf('claudePaths', isStringArray);
+  dropIf('hookMeta', (v) => v != null && typeof v === 'object' && !Array.isArray(v));
+
+  out.configVersion = CURRENT_CONFIG_VERSION;
+  return out;
+}

package/src/lib/update-check.js

@@ -1,53 +1,19 @@
 /**
- * CLI 업데이트 검사: npm 레지스트리에서 최신버전을 조회해 config.json에 캐시하고,
- * 현재 버전과 비교해 업데이트 여부를 판정한다.
+ * CLI 업데이트 검사: TUI(대시보드) 진입 시 npm 레지스트리에서 latest를 1회 조회하고,
+ * 현재 버전과 문자열이 다르면 업데이트가 있다고 판정한다.
  *
  * 설계 원칙
- *  - 화면(메인 대시보드)은 캐시(getUpdateInfo)만 읽어 즉시 렌더 → startup 지연 0.
- *  - 네트워크 조회(refreshCache)는 백그라운드/sync 시점에 돌아 캐시를 채우고, 결과는 "다음 렌더"에 반영된다.
- *  - 어떤 실패(네트워크·404·파싱·옵트아웃)도 조용히 흘려보내 본 기능(대시보드)을 절대 막지 않는다.
+ *  - update 제안은 대화형 TUI에서만 뜬다. 비대화형(sync·스크립트)은 대상 아님 → 캐시/TTL 불필요.
+ *  - checkLatestVersion()을 TUI 진입 시 1회 await로 호출(짧은 타임아웃), 결과를 세션 메모리에 담아 배너 판정에 쓴다.
+ *  - 어떤 실패(네트워크·404·파싱·옵트아웃)도 조용히 null로 흘려보내 대시보드를 절대 막지 않는다.
  */
-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;
-}
+const FETCH_TIMEOUT_MS = 1500; // TUI 진입 조회 상한 — 오프라인/지연 시 이 시간 후 배너 없이 진행
 
 /** 업데이트 알림을 끄는 환경인지. 옵트아웃 env 또는 dev(TOKENPHAGE_API 세팅)면 조회·표시 모두 스킵. */
 export function isUpdateNotifierDisabled() {
@@ -55,23 +21,27 @@ export function isUpdateNotifierDisabled() {
 }
 
 /**
- * 캐시(cfg.latestVersion)와 현재 버전을 비교해 업데이트 정보를 반환한다. 네트워크를 쓰지 않는 동기 함수.
+ * 조회한 latest와 현재 버전을 비교해 업데이트 정보를 반환한다. 순수 함수(네트워크·env·캐시 없음).
+ * update 액션은 항상 `@latest`를 설치하므로 "설치본 ≠ latest"가 곧 "업데이트하면 바뀜"과 일치한다.
+ * 프리릴리스 접미사(-BETA)도 파싱 없이 문자열 비교라 안전하다.
  * @param {string} currentVersion 현재 설치 버전(package.json)
- * @param {object} cfg loadConfig() 결과(또는 동등한 객체)
+ * @param {string|null|undefined} latest checkLatestVersion() 결과(조회 실패/옵트아웃 시 null)
  * @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) {
+export function getUpdateInfo(currentVersion, latest) {
+  if (latest && latest !== currentVersion) {
     return { hasUpdate: true, latest, current: currentVersion };
   }
   return { hasUpdate: false };
 }
 
-/** npm 레지스트리에서 latest 버전 문자열을 조회한다. 실패(타임아웃·404·파싱)는 모두 null. */
-async function fetchLatestFromNpm() {
+/**
+ * npm 레지스트리에서 latest 버전 문자열을 1회 조회한다. TUI 진입 시 한 번 await로 호출해 세션 동안 재사용한다.
+ * 옵트아웃/실패(타임아웃·404·파싱)는 모두 null — 절대 throw하지 않는다.
+ * @returns {Promise<string|null>}
+ */
+export async function checkLatestVersion() {
+  if (isUpdateNotifierDisabled()) return null; // 옵트아웃/dev → 조회 스킵
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
   try {
@@ -85,20 +55,3 @@ async function fetchLatestFromNpm() {
     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/scheduler.js

@@ -1,5 +1,5 @@
 import { execFileSync } from 'child_process';
-import { mkdirSync, writeFileSync, unlinkSync, realpathSync, existsSync } from 'fs';
+import { mkdirSync, writeFileSync, unlinkSync, realpathSync, existsSync, readFileSync } from 'fs';
 import { homedir, tmpdir, userInfo } from 'os';
 import { join } from 'path';
 
@@ -57,8 +57,8 @@ function plistPath() {
   return join(homedir(), 'Library', 'LaunchAgents', `${TASK_LABEL}.plist`);
 }
 
-// macOS용 node 탐색 래퍼 셸 스크립트 경로 (~/.tokenphage/run-sync.sh).
-function syncScriptPathMac() {
+// macOS·Linux 공용 node 탐색 래퍼 셸 스크립트 경로 (~/.tokenphage/run-sync.sh).
+function syncScriptPathSh() {
   return join(homedir(), '.tokenphage', 'run-sync.sh');
 }
 
@@ -175,7 +175,7 @@ function installMac() {
   const { script } = resolveTokenphageBinary();
   const logPath = ensureLogDir();
   const path = plistPath();
-  const wrapper = syncScriptPathMac();
+  const wrapper = syncScriptPathSh();
   mkdirSync(join(homedir(), 'Library', 'LaunchAgents'), { recursive: true });
   mkdirSync(join(homedir(), '.tokenphage'), { recursive: true });
 
@@ -199,7 +199,7 @@ function installMac() {
 // macOS 제거: launchd 등록 해제 후 plist·래퍼 파일을 삭제한다(best-effort). removed 여부를 반환.
 function uninstallMac() {
   const path = plistPath();
-  const wrapper = syncScriptPathMac();
+  const wrapper = syncScriptPathSh();
   const fileExisted = existsSync(path);
   // best-effort 해제 — exit code는 신뢰할 수 없다(거짓 양성).
   launchctlBootout();
@@ -426,18 +426,182 @@ function uninstallWindows() {
   return { platform: 'win32', removed };
 }
 
+// ─── Linux (cron) ─────────────────────────────────────────────────────────────
+
+// crontab 관리 마커: BEGIN..END로 우리 블록만 감싸 멱등 설치/제거 시 식별한다.
+export const CRON_BEGIN = `# BEGIN ${TASK_LABEL} (managed by tokenphage-cli — do not edit)`;
+export const CRON_END = `# END ${TASK_LABEL}`;
+
+// 매일 04:00 sync를 도는 crontab 블록을 만든다. cron은 PATH가 빈약하므로 명령을
+// 직접 부르지 않고 node 탐색 sh 래퍼를 호출하며, 출력은 로그로 리다이렉트한다.
+// 인용은 두 계층을 모두 처리한다: shSingleQuote로 셸 인용(공백·특수문자·한글 안전)한
+// 뒤, cron 파서가 명령 필드에서 개행으로 해석하는 '%'를 '\%'로 이스케이프한다.
+// 경로에 개행이 있으면 단일 crontab 엔트리로 표현할 수 없으므로 설치를 중단한다.
+export function buildCronBlock(wrapperPath, logPath) {
+  for (const p of [wrapperPath, logPath]) {
+    if (/\n/.test(p)) throw new Error(`경로에 개행이 있어 cron 엔트리를 만들 수 없습니다: ${JSON.stringify(p)}`);
+  }
+  const schedule = `${SCHEDULE_MINUTE} ${SCHEDULE_HOUR} * * *`; // "0 4 * * *"
+  const cronArg = (s) => shSingleQuote(s).replace(/%/g, '\\%'); // 셸 인용 후 cron '%' 이스케이프(순서 중요)
+  const line = `${schedule} /bin/sh ${cronArg(wrapperPath)} >> ${cronArg(logPath)} 2>&1`;
+  return `${CRON_BEGIN}\n${line}\n${CRON_END}`;
+}
+
+// 기존 crontab 문자열에서 우리 BEGIN..END 블록만 제거한다(남의 항목은 보존).
+// 정규식 대신 라인 단위 매칭으로 사용자 라인을 오검출하지 않는다. 완결된 BEGIN..END
+// 페어만 제거하고, END를 못 만난 고아 BEGIN(수동 편집·손상)은 버퍼째 되살려 그 뒤
+// 사용자 라인이 통째로 삭제되는 데이터 손실을 막는다(파괴적 해석 대신 보존).
+export function removeCronBlock(existing) {
+  const lines = String(existing).split('\n');
+  const out = [];
+  let buffer = null; // 미종료 BEGIN 이후 라인을 임시 보관
+  for (const line of lines) {
+    if (line === CRON_BEGIN) {
+      if (buffer !== null) out.push(...buffer); // 직전 고아 BEGIN 블록은 보존
+      buffer = [line];
+      continue;
+    }
+    if (buffer !== null) {
+      if (line === CRON_END) { buffer = null; continue; } // 완결 페어 → 제거 확정
+      buffer.push(line);
+      continue;
+    }
+    out.push(line);
+  }
+  if (buffer !== null) out.push(...buffer); // 고아 BEGIN: 아무것도 삭제하지 않고 원문 보존
+  return out.join('\n');
+}
+
+// 기존 블록 제거 후 새 블록을 append한다. 항상 trailing newline으로 끝낸다
+// (vixie-cron은 마지막 줄 개행이 없으면 거부/경고할 수 있음).
+export function upsertCronContent(existing, block) {
+  const base = removeCronBlock(existing).replace(/\n+$/, ''); // 꼬리 공백 라인 정리
+  const body = base.length ? `${base}\n${block}` : block;
+  return `${body}\n`;
+}
+
+// crontab 바이너리 존재 여부 (최소/distroless 컨테이너엔 없을 수 있음).
+function hasCrontab() {
+  try {
+    execFileSync('sh', ['-c', 'command -v crontab'], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// 현재 사용자 crontab 전체를 반환한다. '확정된 빈 crontab'만 ''로 취급하고,
+// 그 외 읽기 실패는 fail-closed로 throw한다 — 이 값이 crontab 전체 재기록의 base가
+// 되므로, 애매한 실패를 ''로 흡수하면 사용자의 기존 항목을 통째로 덮어쓸 수 있다.
+function readCrontab() {
+  try {
+    // maxBuffer 상향: 대형(정상) crontab이 기본 1MB를 넘겨 ENOBUFS로 오인 실패하는 것을 막는다.
+    return execFileSync('crontab', ['-l'], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+  } catch (err) {
+    // 빈 crontab: exit≠0 + stderr 'no crontab for <user>' → 이때만 빈 문자열(잃을 항목 없음).
+    const stderr = (err.stderr?.toString() || '').toLowerCase();
+    if (stderr.includes('no crontab')) return '';
+    if (err.code === 'ENOENT') throw new Error('crontab command not found');
+    // 그 외(ENOBUFS·권한·일시 I/O 등)는 파괴적 재기록을 막기 위해 중단한다.
+    throw new Error(`기존 crontab을 안전하게 읽지 못했습니다 (code=${err.code ?? 'unknown'}). 사용자 항목 소실을 막기 위해 중단합니다.`);
+  }
+}
+
+// cron 데몬 가동 여부(best-effort). Debian=cron, RHEL=crond, Alpine=busybox crond.
+// 탐지 실패가 곧 '안 돎'을 뜻하진 않으므로 경고 판단에만 쓰고 hard-fail하지 않는다.
+function detectCronDaemon() {
+  try {
+    execFileSync('sh', ['-c', 'pgrep -x cron || pgrep -x crond'], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// WSL 여부: WSL_DISTRO_NAME env 또는 /proc/version에 microsoft 포함.
+function isWSL() {
+  if (process.env.WSL_DISTRO_NAME) return true;
+  try {
+    return /microsoft|wsl/i.test(readFileSync('/proc/version', 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
+// Linux 설치: sh 래퍼 작성(멱등) → crontab에 마커 블록 upsert → 데몬/WSL 경고.
+function installLinux() {
+  if (!hasCrontab()) {
+    throw new Error(
+      'crontab 명령을 찾을 수 없습니다. cron을 설치한 뒤 다시 시도하세요.\n' +
+      '  Debian/Ubuntu: sudo apt install cron\n' +
+      '  RHEL 계열:     sudo dnf install cronie');
+  }
+  const { script } = resolveTokenphageBinary();
+  const logPath = ensureLogDir();
+  const wrapper = syncScriptPathSh();
+  mkdirSync(join(homedir(), '.tokenphage'), { recursive: true });
+
+  // 래퍼를 먼저 깔고, crontab 라인이 이 래퍼를 가리키게 한다.
+  writeFileSync(wrapper, buildSyncShellScript(script), { mode: 0o755 });
+
+  // 읽기 → 우리 블록 제거 → 새 블록 append → stdin으로 전체 교체(멱등).
+  const next = upsertCronContent(readCrontab(), buildCronBlock(wrapper, logPath));
+  execFileSync('crontab', ['-'], { input: next, encoding: 'utf8' });
+
+  // best-effort 경고 — 등록은 성공했으나 실제 발화 조건을 사용자에게 알린다.
+  if (!detectCronDaemon()) {
+    const startCmd = isWSL()
+      ? 'sudo service cron start'
+      : 'sudo systemctl enable --now crond 2>/dev/null || sudo systemctl enable --now cron    (WSL: sudo service cron start)';
+    console.log('[!] cron 데몬이 실행 중이 아닙니다. 아래로 켜야 04:00 스케줄이 실제로 동작합니다:');
+    console.log(`    ${startCmd}`);
+  }
+  if (isWSL()) {
+    console.log('[!] WSL은 인스턴스가 떠 있는 동안에만 cron이 동작합니다(04:00에 PC·WSL이 켜져 있어야 함).');
+  }
+
+  return {
+    platform: 'linux',
+    method: 'cron',
+    logPath,
+    scheduleSpec: `daily ${String(SCHEDULE_HOUR).padStart(2, '0')}:${String(SCHEDULE_MINUTE).padStart(2, '0')}`,
+    artifactPath: `crontab (${TASK_LABEL})`,
+  };
+}
+
+// Linux 제거: crontab에서 마커 블록 제거 후 래퍼 파일 정리(best-effort). removed 반환.
+function uninstallLinux() {
+  let removed = false;
+  if (hasCrontab()) {
+    const current = readCrontab();
+    if (current.includes(CRON_BEGIN)) {
+      const cleaned = removeCronBlock(current).replace(/\n+$/, '');
+      // 남은 내용이 있으면 개행 보장해 기록, 전부 비면 빈 crontab으로 교체.
+      execFileSync('crontab', ['-'], { input: cleaned.length ? `${cleaned}\n` : '', encoding: 'utf8' });
+      removed = true;
+    }
+  }
+  const wrapper = syncScriptPathSh();
+  if (existsSync(wrapper)) {
+    try { unlinkSync(wrapper); removed = true; } catch { /* noop */ }
+  }
+  return { platform: 'linux', removed };
+}
+
 // ─── Public API ──────────────────────────────────────────────────────────────
 
-/** 현재 OS에 맞는 자동 sync 스케줄을 설치한다 (macOS=launchd / Windows=schtasks). 그 외 OS는 throw. */
+/** 현재 OS에 맞는 자동 sync 스케줄을 설치한다 (macOS=launchd / Windows=schtasks / Linux=cron). 그 외 OS는 throw. */
 export async function installHook() {
   if (process.platform === 'darwin') return installMac();
   if (process.platform === 'win32') return installWindows();
-  throw new Error(`Unsupported OS: ${process.platform}. Only macOS and Windows are supported.`);
+  if (process.platform === 'linux') return installLinux();
+  throw new Error(`Unsupported OS: ${process.platform}. Only macOS, Windows, and Linux are supported.`);
 }
 
-/** 현재 OS의 자동 sync 스케줄을 제거한다 (macOS=launchd / Windows=schtasks). 그 외 OS는 throw. */
+/** 현재 OS의 자동 sync 스케줄을 제거한다 (macOS=launchd / Windows=schtasks / Linux=cron). 그 외 OS는 throw. */
 export async function uninstallHook() {
   if (process.platform === 'darwin') return uninstallMac();
   if (process.platform === 'win32') return uninstallWindows();
-  throw new Error(`Unsupported OS: ${process.platform}. Only macOS and Windows are supported.`);
+  if (process.platform === 'linux') return uninstallLinux();
+  throw new Error(`Unsupported OS: ${process.platform}. Only macOS, Windows, and Linux are supported.`);
 }

package/src/sync.js

@@ -1,3 +1,20 @@
+/**
+ * 서버 HTTP 상태코드를 사용자 대면 메시지로 매핑한다(응답 원문은 노출하지 않음).
+ * @param {number} status HTTP 상태코드
+ * @param {string} [bodyText] 400 세부 분기 판단용 응답 본문
+ * @returns {string} 사용자 메시지
+ */
+export function mapServerError(status, bodyText) {
+  if (status === 401) return 'Authentication expired or invalid. Run `tokenphage login` to sign in again.';
+  if (status === 400) {
+    const lower = (bodyText || '').toLowerCase();
+    if (lower.includes('deviceid')) return 'Your config file looks corrupted. Run `tokenphage login` to re-authenticate.';
+    return 'Request format error. Update the CLI: npm i -g tokenphage@latest';
+  }
+  if (status >= 500) return 'Server temporarily unavailable. Your existing badge data is safe.';
+  return `Server error: ${status}`; // 매핑되지 않은 상태 폴백
+}
+
 /**
  * 집계된 토큰 사용 기록을 서버에 업로드한다 (POST /api/sync).
  * 사용자는 서버가 JWT(Bearer)에서 식별하고, 본문에 deviceId와 records를 담아 보낸다.
@@ -5,7 +22,7 @@
  * @param {string} token    Bearer JWT
  * @param {string} deviceId 기기 식별 UUID
  * @param {Array<{date:string, model:string, inputTok:number, outputTok:number, cacheReadTok:number, cacheCreateTok:number}>} records 날짜·모델별 집계 레코드
- * @throws {Error} 응답이 2xx가 아니면 status와 응답 본문을 담아 throw
+ * @throws {Error} 2xx가 아니면 mapServerError 메시지로 throw
  */
 export async function syncRecords(apiBase, token, deviceId, records) {
   // Node 18+ 전역 fetch 사용 (node-fetch 의존성 불필요).
@@ -14,7 +31,7 @@ export async function syncRecords(apiBase, token, deviceId, records) {
     headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` },
     body: JSON.stringify({ deviceId, records }),
   });
-  if (!res.ok) throw new Error(`Server error: ${res.status} ${await res.text()}`);
+  if (!res.ok) throw new Error(mapServerError(res.status, await res.text()));
 }
 
 /**
@@ -29,8 +46,12 @@ export async function resetData(apiBase, token) {
   });
   if (!res.ok) {
     const text = await res.text();
-    let msg = text;
-    try { msg = JSON.parse(text).message ?? text; } catch {  }
-    throw new Error(res.status === 429 ? msg : `Server error: ${res.status} ${msg}`);
+    if (res.status === 429) {
+      // 429: 서버 쿨다운 메시지를 그대로 노출
+      let msg = text;
+      try { msg = JSON.parse(text).message ?? text; } catch { /* 비JSON은 원문 */ }
+      throw new Error(msg);
+    }
+    throw new Error(mapServerError(res.status, text));
   }
 }

package/src/ui.js

@@ -127,14 +127,15 @@ export async function promptFirstRun() {
 
 /**
  * 인증된 사용자를 위한 대시보드 메뉴.
- * @param {{ token: string, lastSyncDate: string|null, hookInstalled: boolean, hookMeta: object|null, latestVersion?: string }} cfg
+ * @param {{ token: string, lastSyncDate: string|null, hookInstalled: boolean, hookMeta: object|null }} cfg
+ * @param {string|null} latest TUI 진입 시 조회한 npm 최신버전(조회 실패/옵트아웃 시 null)
  * @returns {'update' | 'sync' | 'install-hook' | 'uninstall-hook' | 'advanced' | 'exit'}
  */
-export async function promptDashboard(cfg) {
+export async function promptDashboard(cfg, latest) {
   printWelcome();
 
-  // 캐시된 npm 최신버전과 현재 버전을 비교해, 새 버전이 있을 때만 민트 배너를 출력한다(네트워크 X).
-  const update = getUpdateInfo(version, cfg);
+  // TUI 진입 시 조회한 npm 최신버전과 현재 버전을 비교해, 다를 때만 민트 배너를 출력한다.
+  const update = getUpdateInfo(version, latest);
   if (update.hasUpdate) {
     const bar = accent('  ┃ ');
     console.log(bar + accent(`⬆  Update available  v${update.current} → v${update.latest}`));