tokenphage 2026.7.0-BETA

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kobenlys
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# TokenPhage CLI
+
+> AI 토큰 사용량을 GitHub README 배지로 보여주는 CLI.
+
+Claude Code와 Codex의 토큰 사용량을 모아 GitHub README에 붙일 수 있는 배지로 만들어 줍니다.
+
+---
+
+## 요구 사항
+
+- **Node.js 20.17 이상**
+- macOS 또는 Windows (자동 동기화 사용 시)
+- GitHub 계정
+
+## 설치
+
+```bash
+npm install -g tokenphage
+```
+
+설치 후 `tokenphage` 명령을 쓸 수 있습니다.
+
+## 빠른 시작
+
+```bash
+tokenphage                       # 대화형 화면 실행 (처음이면 로그인부터 안내)
+tokenphage login <github-id>     # GitHub 계정 인증
+tokenphage sync                  # 지금 사용량 동기화
+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로 종료**합니다.
+
+### 처음 실행 (로그인 전)
+```
+  ❯ Authenticate with Gist     ← 로그인 시작
+    Exit
+```
+`Authenticate with Gist`를 고르면 인증을 진행하고, 끝나면 자동으로 첫 동기화까지 마친 뒤 대시보드로 들어갑니다.
+
+### 대시보드 (로그인 후)
+```
+  Authenticated as @your-id
+  Last sync: 2026-06-22
+  Auto-sync enabled (daily 04:00)
+
+  ❯ Sync now              ← 지금 동기화
+    Disable auto-sync     ← (또는) Enable auto-sync
+    Advanced settings
+    Exit
+```
+- **Sync now** — 지금 바로 동기화
+- **Enable / Disable auto-sync** — 자동 동기화 켜기/끄기 (현재 상태에 맞춰 표시)
+- **Advanced settings** — 데이터 초기화 등
+- **Exit** — 종료
+
+### Advanced settings
+```
+  ❯ Reset all data    ← 데이터 전체 초기화
+    Back
+```
+**Reset all data**는 서버에 쌓인 토큰 데이터를 모두 지우고 처음부터 다시 동기화합니다. 되돌릴 수 없어서, 확인을 위해 **본인 GitHub 아이디를 직접 입력**해야 진행됩니다. (로컬 기록은 건드리지 않으며, 24시간에 한 번만 가능)
+
+---
+
+## 로그인 (Gist 인증)
+
+비밀번호 없이, **본인 GitHub 계정으로 공개 Gist를 만들 수 있다는 점**으로 계정을 인증합니다.
+
+1. 화면에 인증용 문자열이 표시됩니다.
+2. 안내대로 `https://gist.github.com/new`에서 **공개(public) Gist**를 만듭니다.
+   - 파일 이름: `tokenphage.txt`
+   - 내용: 화면에 나온 인증 문자열
+3. 만들어진 Gist의 주소(URL)나 ID를 붙여넣습니다.
+4. 인증이 끝나면 로그인이 완료됩니다.
+
+---
+
+## 자동 동기화
+
+`install-hook`을 켜면 매일 **오전 4시**에 자동으로 동기화됩니다(macOS·Windows). 컴퓨터를 거의 안 쓰는 시간대라 작업을 방해하지 않습니다.
+
+- 켜기: `tokenphage install-hook` (또는 대시보드 → Enable auto-sync)
+- 끄기: `tokenphage uninstall-hook` (또는 대시보드 → Disable auto-sync)
+- 실행 기록은 `~/.tokenphage/logs/sync.log`에서 볼 수 있습니다.
+
+처음 설정할 때 권한을 묻는다면:
+- **macOS** — 시스템 설정 → 개인정보 보호 및 보안 → 자동화 허용
+- **Windows** — **관리자 권한 터미널**에서 다시 실행
+
+---
+
+## 저장되는 곳
+
+로그인 정보와 설정은 `~/.tokenphage/` 폴더에 저장됩니다. 로그아웃하거나 초기화하려면 이 폴더를 지우면 됩니다.
+
+---
+
+## 토큰이 누락되지 않게 하기
+
+Claude Code는 오래된 세션 기록을 자동으로 지울 수 있고, 지워진 기록의 토큰은 다시 집계되지 않습니다. 그래서 로그인 직후 CLI가 **"기록을 계속 보관할지"** 물어봅니다. **Yes**로 두면 이후 모든 토큰이 빠짐없이 집계됩니다.
+
+---
+
+## 문제 해결
+
+| 증상 | 해결 |
+|------|------|
+| `Not authenticated` 라고 나옴 | 먼저 `tokenphage login <github-id>` 로 로그인 |
+| `login` 이 바로 종료됨 | 일반 터미널(입력 가능한 창)에서 실행 |
+| 자동 동기화 설정 중 권한 거부 | macOS: 자동화 권한 허용 / Windows: 관리자 터미널에서 재실행 |
+| 자동 동기화가 안 도는 것 같음 | `~/.tokenphage/logs/sync.log` 확인 |
+| 토큰이 누락됨 | 로그인 직후 안내된 "기록 보관" 설정을 켰는지 확인 |

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "tokenphage",
+  "version": "2026.7.0-BETA",
+  "description": "AI 토큰 사용량 GitHub README 뱃지",
+  "author": "kobenlys <kobenlys@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TOKENPHAGE/tokenphage-cli.git"
+  },
+  "main": "src/index.js",
+  "bin": {
+    "tokenphage": "./src/index.js"
+  },
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "cross-env TOKENPHAGE_API=http://localhost:8080 node src/index.js",
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.5.0",
+    "chalk": "^5.6.2",
+    "commander": "^12.1.0",
+    "glob": "^11.0.0",
+    "gradient-string": "^3.0.0",
+    "open": "^10.1.0"
+  },
+  "devDependencies": {
+    "cross-env": "^7.0.3"
+  },
+  "overrides": {
+    "mute-stream": "^3.0.0"
+  },
+  "engines": {
+    "node": "^20.17.0 || ^22.13.0 || >=23.5.0"
+  }
+}

package/src/animated-select.js

@@ -0,0 +1,109 @@
+import {
+  createPrompt,
+  useState,
+  useEffect,
+  useKeypress,
+  usePrefix,
+  makeTheme,
+  isEnterKey,
+  isUpKey,
+  isDownKey,
+} from '@inquirer/core';
+import chalk from 'chalk';
+import { flowText, accent } from './gradient.js';
+
+// 애니메이션 타이밍: PERIOD(ms)마다 한 프레임, CYCLE 프레임에 그라데이션 한 바퀴.
+// 80ms × 24 ≈ 1.9초/바퀴 — PERIOD는 깜빡임/CPU 안전선(80ms)을 유지
+const PERIOD = 80;
+const CYCLE = 24;
+
+// 흐르는 애니메이션 활성 조건. 비TTY·NO_COLOR·dumb 터미널·색 미지원이거나
+// TOKENPHAGE_NO_ANIM=1(reduced-motion 옵트아웃)이면 정적으로 폴백한다.
+const ANIM_ENABLED =
+  process.stdout.isTTY === true &&
+  !process.env.NO_COLOR &&
+  process.env.TERM !== 'dumb' &&
+  chalk.level > 0 &&
+  process.env.TOKENPHAGE_NO_ANIM !== '1';
+
+// 메뉴(입력창 없음) 표시 중 터미널 커서를 숨기기 위한 DECTCEM 시퀀스.
+const HIDE_CURSOR = '\x1B[?25l';
+const SHOW_CURSOR = '\x1B[?25h';
+// 커서 복원(비TTY면 무시). 종료/언마운트 모든 경로에서 호출.
+const showCursor = () => { if (process.stdout.isTTY) process.stdout.write(SHOW_CURSOR); };
+
+/**
+ * Esc 즉시 종료 + (선택적) 흐르는 그라데이션을 지원하는 커스텀 select.
+ * choice에 `flow: true`가 있으면 커서 위치와 무관하게 항상 그라데이션이 흐른다.
+ * pagination/disabled/검색은 메뉴 항목이 적어 의도적으로 생략한다.
+ */
+export const selectWithEsc = createPrompt((config, done) => {
+  const { message, choices } = config;
+  const theme = makeTheme(config.theme);
+  const [status, setStatus] = useState('idle');
+  const [active, setActive] = useState(0);
+  const [frame, setFrame] = useState(0);
+
+  const prefix = usePrefix({ status, theme });
+  const hasFlow = choices.some((choice) => choice.flow);
+
+  // 흐르는 그라데이션 타이머. flow 항목이 있고 애니메이션이 켜졌을 때만 가동.
+  // 시간 기반 phase라 useState 업데이터 함수 미지원 제약을 피하고 drift도 없다.
+  useEffect(() => {
+    if (status === 'done' || !ANIM_ENABLED || !hasFlow) return undefined;
+    const id = setInterval(() => {
+      setFrame(Math.floor(Date.now() / PERIOD) % CYCLE);
+    }, PERIOD);
+    return () => clearInterval(id);
+  }, [status]);
+
+  // 메뉴 표시 중에는 입력창이 없으므로 터미널 커서를 숨긴다.
+  // done()/정상 종료 시 언마운트 cleanup으로 복원된다. Esc 경로는 키 핸들러에서 별도 복원.
+  useEffect(() => {
+    if (process.stdout.isTTY) process.stdout.write(HIDE_CURSOR);
+    return () => showCursor();
+  }, []);
+
+  useKeypress((key) => {
+    if (key.name === 'escape') {
+      showCursor();    // process.exit는 useEffect cleanup을 건너뛰므로 명시 복원
+      process.exit(0); // 기존 selectWithEsc 동작 유지: Esc는 즉시 종료
+    } else if (isEnterKey(key)) {
+      setStatus('done');
+      done(choices[active].value);
+    } else if (isUpKey(key)) {
+      setActive((active - 1 + choices.length) % choices.length);
+    } else if (isDownKey(key)) {
+      setActive((active + 1) % choices.length);
+    }
+  });
+
+  const header = `${prefix} ${theme.style.message(message, status)}`;
+
+  // 완료 시: 선택값 한 줄만 남기고 리스트/설명은 지운다.
+  if (status === 'done') {
+    const selected = choices[active];
+    return `${header} ${accent(selected.short ?? selected.name)}`;
+  }
+
+  const phase = frame / CYCLE;
+  const lines = choices.map((choice, i) => {
+    const isActive = i === active;
+    const pointer = isActive ? accent('❯ ') : '  ';
+
+    let label;
+    if (choice.flow && ANIM_ENABLED) {
+      label = flowText(choice.name, phase); // 흐르는 그라데이션 (커서 무관)
+    } else if (choice.flow || isActive) {
+      label = accent(choice.name); // 애니 꺼진 flow 항목 / 커서 항목 → 정적 민트
+    } else {
+      label = choice.name; // 그 외 → 평문
+    }
+    return pointer + label;
+  });
+
+  const activeChoice = choices[active];
+  const bottom = activeChoice?.description ? accent(activeChoice.description) : '';
+
+  return [`${header}\n${lines.join('\n')}`, bottom];
+});

package/src/auth.js

@@ -0,0 +1,203 @@
+import { readFileSync, writeFileSync, mkdirSync, chmodSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+
+// 로컬 설정 파일 경로: ~/.tokenphage/config.json (JWT·deviceId·sync 상태 보관)
+const CONFIG_DIR = join(homedir(), '.tokenphage');
+const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
+
+/** config.json을 읽어 객체로 반환한다. 파일이 없거나 손상됐으면 빈 객체. */
+export function loadConfig() {
+  try { return JSON.parse(readFileSync(CONFIG_PATH, 'utf8')); }
+  catch { return {}; }
+}
+
+/** config 객체를 config.json에 저장한다. JWT가 담기므로 소유자 전용(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 미지원 — 무시 */ }
+}
+
+/** 저장된 JWT를 반환한다. 없으면 null. */
+export function loadToken() {
+  return loadConfig().token ?? null;
+}
+
+/** 다른 설정은 보존한 채 JWT만 갱신해 저장한다. */
+export function saveToken(token) {
+  saveConfig({ ...loadConfig(), token });
+}
+
+/** 기기 식별용 deviceId(UUID)를 반환한다. 없으면 새로 발급·저장한 뒤 반환한다. */
+export function getOrCreateDeviceId() {
+  const cfg = loadConfig();
+  if (cfg.deviceId) return cfg.deviceId;
+  const deviceId = randomUUID();
+  saveConfig({ ...cfg, deviceId });
+  return deviceId;
+}
+
+/**
+ * 훅 설치 상태를 설정에 기록한다.
+ * 설치 시 설치 시각(ISO)과 메타데이터를 함께 저장하고, 해제 시 둘 다 null로 비운다.
+ */
+export function setHookInstalled(installed, meta = {}) {
+  const cfg = loadConfig();
+  saveConfig({
+    ...cfg,
+    hookInstalled: installed,
+    hookInstalledAt: installed ? new Date().toISOString() : null,
+    hookMeta: installed ? meta : null,
+  });
+}
+
+/** config.json의 claudePaths(사용자 지정 Claude 디렉터리 목록)를 반환한다. 비배열이면 빈 배열. */
+export function getCustomClaudePaths() {
+  const paths = loadConfig().claudePaths;
+  return Array.isArray(paths) ? paths : [];
+}
+
+/** 마지막 sync 완료 날짜(YYYY-MM-DD)를 반환한다. 없으면 null. */
+export function getLastSyncDate() { return loadConfig().lastSyncDate ?? null; }
+
+/** 마지막 sync 날짜를 저장한다. 다음 sync는 이 날짜 이후만 증분 파싱한다. */
+export function saveLastSyncDate(date) {
+  saveConfig({ ...loadConfig(), lastSyncDate: date });
+}
+
+/** lastSyncDate를 제거해 다음 sync가 전체 히스토리를 재파싱하도록 한다. token/deviceId는 보존. */
+export function clearLastSyncDate() {
+  const { lastSyncDate: _omit, ...rest } = loadConfig();
+  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';
+
+/**
+ * Gist URL 또는 원본 ID에서 gist ID만 추출한다.
+ *   https://gist.github.com/octocat/abc123def456 → abc123def456
+ *   https://gist.github.com/abc123def456         → abc123def456
+ *   abc123def456                                  → abc123def456
+ */
+export function parseGistId(input) {
+  if (!input) return '';
+  const trimmed = input.trim();
+  // URL이면 (사용자명/) 뒤의 ID 토큰만 캡처하고, 그 외에는 앞뒤 슬래시만 제거한다.
+  const match = trimmed.match(/gist\.github\.com\/(?:[^/]+\/)?([A-Za-z0-9]+)/);
+  if (match) return match[1];
+  return trimmed.replace(/^\/+|\/+$/g, '');
+}
+
+/** url에 JSON body를 POST하고 {ok, status, body}를 반환한다. 응답이 JSON이 아니면 {error: 원문}으로 감싼다. */
+async function postJson(url, body) {
+  // Node 18+ 전역 fetch 사용 (node-fetch 의존성 불필요).
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  const text = await res.text();
+  let parsed;
+  try { parsed = JSON.parse(text); } catch { parsed = { error: text }; } // 비JSON 응답 방어
+  return { ok: res.ok, status: res.status, body: parsed };
+}
+
+/** 질문을 출력하고 표준입력 한 줄을 받아 trim한 문자열로 resolve한다. (readline 지연 로드) */
+function prompt(question) {
+  return import('readline').then(({ default: readline }) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise(resolve => {
+      rl.question(question, answer => { rl.close(); resolve(answer.trim()); });
+    });
+  });
+}
+
+/** ISO 문자열을 로컬 'YYYY-MM-DD HH:mm'로 포맷한다. */
+function formatExpiry(iso) {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso; // 파싱 실패 시 원문 그대로 (방어)
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+
+/**
+ * Gist 기반 로그인: 챌린지 발급 → 사용자가 Gist 생성 → 검증 → JWT 반환.
+ * username이 없으면 입력을 요청한다.
+ *
+ * @param {string} apiBase API 서버 base URL
+ * @param {string} [username] GitHub 사용자명 (생략 시 프롬프트로 입력)
+ * @returns {Promise<string>} 발급된 JWT
+ */
+export async function gistLogin(apiBase, username) {
+  if (!username) {
+    username = await prompt('GitHub username: ');
+  }
+  if (!username) throw new Error('Username is required.');
+
+  // 1) 서버에 챌린지 요청 — 사용자가 Gist에 적을 검증 문자열을 받는다.
+  const challengeRes = await postJson(`${apiBase}/auth/challenge`, { username });
+  if (!challengeRes.ok) {
+    throw new Error(`Challenge request failed: ${challengeRes.status} ${JSON.stringify(challengeRes.body)}`);
+  }
+  const { challenge, expiresAt } = challengeRes.body ?? {};
+  if (!challenge) {
+    throw new Error(`Unexpected challenge response: ${JSON.stringify(challengeRes.body)}`);
+  }
+
+  // 2) 사용자에게 public Gist 생성 절차를 안내한다.
+  console.log('');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log(' Create a public Gist to prove ownership of your GitHub account.');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('');
+  console.log(`  1) Go to https://gist.github.com/new`);
+  console.log(`  2) Filename:  ${VERIFICATION_FILE}`);
+  console.log(`     Content:`);
+  console.log('');
+  console.log(`         ${challenge}`);
+  console.log('');
+  console.log(`  3) Click "Create public gist" (NOT Secret gist!)`);
+  console.log(`  4) Paste the generated Gist URL or ID below`);
+  console.log('');
+  console.log(`  Expires: ${formatExpiry(expiresAt)}`);
+  console.log('');
+
+  // 브라우저로 Gist 작성 페이지를 자동으로 열어준다 (실패해도 위 안내대로 수동 진행 가능).
+  try {
+    const { default: open } = await import('open');
+    await open('https://gist.github.com/new');
+  } catch { /* 브라우저 자동 실행 실패는 무시 */ }
+
+  // 3) 사용자가 만든 Gist의 URL/ID를 입력받아 ID만 추출한다.
+  const rawInput = await prompt('Gist URL or ID: ');
+  const gistId = parseGistId(rawInput);
+  if (!gistId) throw new Error('Could not parse a Gist ID from the input.');
+
+  // 4) 서버에 검증 요청 — Gist 내용이 챌린지와 일치하면 JWT를 발급받는다.
+  const verifyRes = await postJson(`${apiBase}/auth/verify`, { username, gistId });
+  if (!verifyRes.ok) {
+    const err = verifyRes.body?.error ?? 'unknown';
+    throw new Error(`Verification failed (${verifyRes.status}): ${err}`);
+  }
+  const { token, githubId, username: confirmedUsername } = verifyRes.body ?? {};
+  if (!token) {
+    throw new Error(`Verification response missing token: ${JSON.stringify(verifyRes.body)}`);
+  }
+  console.log('');
+  console.log(`[OK] Authenticated as ${confirmedUsername} (github_id=${githubId})`);
+  return token;
+}

package/src/gradient.js

@@ -0,0 +1,58 @@
+import chalk from 'chalk';
+
+// 로고 세로 그라데이션 색 스톱 (위: 밝은 라벤더 보라 → 아래: 미디엄 퍼플)
+export const PURPLE_STOPS = [
+  [221, 198, 255], // #DDC6FF
+  [165, 124, 255], // #A57CFF
+  [110, 70, 168],  // #6E46A8
+];
+
+// 느낌표 강조 그라데이션 색 스톱 (위: 밝은 민트 → 아래: 진한 민트 시안)
+export const ACCENT_STOPS = [
+  [94, 234, 212], // #5EEAD4
+  [45, 212, 191], // #2DD4BF
+];
+
+// 흐르는 그라데이션 색 스톱 (쨍한 노랑 → 흰색 → 쨍한 노랑). 양 끝이 같아 매끄럽게 순환한다.
+export const FLOW_STOPS = [
+  [255, 214, 0],   // #FFD600
+  [255, 255, 255], // #FFFFFF
+  [255, 214, 0],   // #FFD600
+];
+
+// CLI 공용 하이라이트 색 — 느낌표 강조색(민트 시안)과 통일.
+// 메뉴 선택 하이라이트, 강조 텍스트 등 모든 하이라이팅은 이 색을 사용한다.
+export const ACCENT_HEX = '#5EEAD4';
+export const accent = (text) => chalk.hex(ACCENT_HEX)(text);
+
+/** 두 RGB 색 사이를 t(0~1) 비율로 선형 보간해 hex 문자열로 반환. */
+function lerpHex(from, to, t) {
+  const ch = (a, b) => Math.round(a + (b - a) * t).toString(16).padStart(2, '0');
+  return `#${ch(from[0], to[0])}${ch(from[1], to[1])}${ch(from[2], to[2])}`;
+}
+
+/** 0~1 위치를 다색 스톱 위에서 보간해 hex 색을 반환. */
+export function colorAt(t, stops) {
+  const seg = t * (stops.length - 1);
+  const idx = Math.min(Math.floor(seg), stops.length - 2);
+  return lerpHex(stops[idx], stops[idx + 1], seg - idx);
+}
+
+/**
+ * 문자열의 각 문자에 위상(phase) offset을 줘 시간에 따라 흐르는 그라데이션을 입힌다.
+ * 문자 위치(i/n)에 phase를 더해 0~1로 wrap한 뒤 colorAt으로 색을 구한다.
+ * @param {string} text  대상 문자열
+ * @param {number} phase 0~1 위상 offset (프레임/시간 기반으로 증가시키면 흐르는 효과)
+ * @param {number[][]} stops 색 스톱 배열 (기본 FLOW_STOPS)
+ * @returns {string} ANSI 색이 입혀진 문자열
+ */
+export function flowText(text, phase, stops = FLOW_STOPS) {
+  const chars = [...text]; // 유니코드 안전 분해
+  const n = Math.max(chars.length, 1);
+  return chars
+    .map((char, i) => {
+      const t = (((i / n) + phase) % 1 + 1) % 1; // 음수 방지 wrap
+      return chalk.hex(colorAt(t, stops))(char);
+    })
+    .join('');
+}