tokenphage 2026.7.0-BETA

package/src/scheduler.js

@@ -0,0 +1,443 @@
+import { execFileSync } from 'child_process';
+import { mkdirSync, writeFileSync, unlinkSync, realpathSync, existsSync } from 'fs';
+import { homedir, tmpdir, userInfo } from 'os';
+import { join } from 'path';
+
+export const TASK_LABEL = 'dev.tokenphage.sync';
+const WIN_TASK_NAME = 'tokenphage-sync';
+const SCHEDULE_HOUR = 4;
+const SCHEDULE_MINUTE = 0;
+
+/** ~/.tokenphage/logs 디렉터리를 보장하고 sync.log의 절대경로를 반환한다. */
+export function ensureLogDir() {
+  const dir = join(homedir(), '.tokenphage', 'logs');
+  mkdirSync(dir, { recursive: true });
+  return join(dir, 'sync.log');
+}
+
+/**
+ * 스케줄러가 실행할 node 바이너리와 이 CLI 스크립트의 절대경로를 반환한다(심링크는 realpath로 해소).
+ * 예) 전역 설치(npm i -g) 상태:
+ *   node    = /Users/me/.nvm/versions/node/v22.17.1/bin/node          (process.execPath)
+ *   argv[1] = /usr/local/bin/tokenphage                               (← bin 심링크)
+ *   script  = /usr/local/lib/node_modules/tokenphage/src/index.js     (realpath로 해소된 실제 파일)
+ * 로컬 개발(node src/index.js) 시엔 argv[1]이 이미 실파일이라 script도 그대로 .../src/index.js.
+ */
+export function resolveTokenphageBinary() {
+  const node = process.execPath;
+  const script = realpathSync(process.argv[1]);
+  return { node, script };
+}
+
+// XML 특수문자(& < > " ')를 엔티티로 치환한다 (plist·Task XML 삽입용).
+function escapeXml(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+// POSIX 셸 single-quote escaping: 경로에 공백·특수문자가 있어도 안전하게 인용한다.
+function shSingleQuote(s) {
+  return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+
+// PowerShell single-quote literal escaping: 내부 작은따옴표(')만 ''로 이중화하면 된다.
+// cmd 파싱을 거치지 않으므로 공백·% ! ^ & 등 메타문자 걱정이 없다.
+function psSingleQuote(s) {
+  return `'${String(s).replace(/'/g, `''`)}'`;
+}
+
+// ─── macOS (launchd) ────────────────────────────────────────────────────────
+
+// launchd 에이전트 plist 파일 경로 (~/Library/LaunchAgents).
+function plistPath() {
+  return join(homedir(), 'Library', 'LaunchAgents', `${TASK_LABEL}.plist`);
+}
+
+// macOS용 node 탐색 래퍼 셸 스크립트 경로 (~/.tokenphage/run-sync.sh).
+function syncScriptPathMac() {
+  return join(homedir(), '.tokenphage', 'run-sync.sh');
+}
+
+// launchd가 직접 node 절대경로를 들고 있으면 nvm/fnm 등 버전 매니저가
+// 경로를 바꾸는 순간 스케줄이 조용히 깨진다. 대신 실행 시점에 node를
+// 동적으로 탐색하는 래퍼를 거치게 해, 버전이 바뀌어도 알아서 따라가게 한다.
+// 특정 사용자·버전 경로를 plist에 하드코딩하지 않는다.
+function buildSyncShellScript(script) {
+  return `#!/bin/sh
+# tokenphage auto-sync launcher — generated by tokenphage-cli.
+# node 바이너리를 실행 시점에 탐색한다 (nvm 등 버전 매니저 변경에도 견고).
+
+# ls/sort/tail/command 등 coreutils가 항상 잡히도록 표준 PATH를 보장한다.
+export PATH="/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:$PATH"
+
+SCRIPT=${shSingleQuote(script)}
+
+resolve_node() {
+  # 1) PATH 상의 node (Homebrew / 시스템 / launchd PATH)
+  if command -v node >/dev/null 2>&1; then command -v node; return 0; fi
+  # 2) nvm: 설치된 버전 중 가장 최신
+  nvm_root="$HOME/.nvm/versions/node"
+  if [ -d "$nvm_root" ]; then
+    newest=$(ls -1 "$nvm_root" 2>/dev/null | sort -V | tail -1)
+    if [ -n "$newest" ] && [ -x "$nvm_root/$newest/bin/node" ]; then
+      echo "$nvm_root/$newest/bin/node"; return 0
+    fi
+  fi
+  return 1
+}
+
+NODE=$(resolve_node)
+if [ -z "$NODE" ]; then
+  echo "tokenphage: node 바이너리를 찾지 못했습니다 (PATH 및 ~/.nvm 확인)" >&2
+  exit 127
+fi
+exec "$NODE" "$SCRIPT" sync
+`;
+}
+
+// launchd plist 문자열을 만든다. 매일 정해진 시각에 /bin/sh로 래퍼를 실행하고 stdout/stderr를 로그로 남기게 정의한다.
+function buildPlist(wrapperPath, logPath) {
+  const home = homedir();
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTD/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${escapeXml(TASK_LABEL)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/sh</string>
+    <string>${escapeXml(wrapperPath)}</string>
+  </array>
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Hour</key><integer>${SCHEDULE_HOUR}</integer>
+    <key>Minute</key><integer>${SCHEDULE_MINUTE}</integer>
+  </dict>
+  <key>RunAtLoad</key>
+  <false/>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(logPath)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>HOME</key>
+    <string>${escapeXml(home)}</string>
+    <key>PATH</key>
+    <string>/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin</string>
+  </dict>
+</dict>
+</plist>
+`;
+}
+
+// 기존 launchd 등록을 해제한다 (bootout 실패 시 구버전 unload로 폴백). 성공 여부를 boolean으로 반환.
+function launchctlBootout() {
+  const uid = userInfo().uid;
+  const path = plistPath();
+  try {
+    execFileSync('launchctl', ['bootout', `gui/${uid}/${TASK_LABEL}`], { stdio: 'ignore' });
+    return true;
+  } catch {
+    try {
+      execFileSync('launchctl', ['unload', path], { stdio: 'ignore' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+// plist를 launchd에 등록한다 (bootstrap 실패 시 구버전 load로 폴백, 둘 다 실패하면 안내 메시지와 함께 throw).
+function launchctlBootstrap() {
+  const uid = userInfo().uid;
+  const path = plistPath();
+  try {
+    execFileSync('launchctl', ['bootstrap', `gui/${uid}`, path], { stdio: 'pipe' });
+  } catch (err) {
+    try {
+      execFileSync('launchctl', ['load', path], { stdio: 'pipe' });
+    } catch (err2) {
+      const msg = (err2.stderr?.toString() || err.stderr?.toString() || err.message || '').trim();
+      throw new Error(`launchctl registration failed: ${msg}\n` +
+        'If permission was denied, check System Settings → Privacy & Security → Automation.');
+    }
+  }
+}
+
+// macOS 설치: node 탐색 래퍼 작성 → plist 작성 → launchd 재등록(멱등). 등록 결과 메타(method/logPath 등)를 반환한다.
+function installMac() {
+  const { script } = resolveTokenphageBinary();
+  const logPath = ensureLogDir();
+  const path = plistPath();
+  const wrapper = syncScriptPathMac();
+  mkdirSync(join(homedir(), 'Library', 'LaunchAgents'), { recursive: true });
+  mkdirSync(join(homedir(), '.tokenphage'), { recursive: true });
+
+  // node 탐색 래퍼를 먼저 깔고, plist는 이 래퍼를 가리키게 한다.
+  writeFileSync(wrapper, buildSyncShellScript(script), { mode: 0o755 });
+
+  // idempotent: 기존 등록 해제 → 덮어쓰기 → 재등록
+  launchctlBootout();
+  writeFileSync(path, buildPlist(wrapper, logPath), { mode: 0o644 });
+  launchctlBootstrap();
+
+  return {
+    platform: 'darwin',
+    method: 'launchd',
+    logPath,
+    scheduleSpec: `daily ${String(SCHEDULE_HOUR).padStart(2, '0')}:${String(SCHEDULE_MINUTE).padStart(2, '0')}`,
+    artifactPath: path,
+  };
+}
+
+// macOS 제거: launchd 등록 해제 후 plist·래퍼 파일을 삭제한다(best-effort). removed 여부를 반환.
+function uninstallMac() {
+  const path = plistPath();
+  const wrapper = syncScriptPathMac();
+  const fileExisted = existsSync(path);
+  // best-effort 해제 — exit code는 신뢰할 수 없다(거짓 양성).
+  launchctlBootout();
+  if (fileExisted) unlinkSync(path);
+  if (existsSync(wrapper)) {
+    try { unlinkSync(wrapper); } catch { /* noop */ }
+  }
+  return { platform: 'darwin', removed: fileExisted };
+}
+
+// ─── Windows (Task Scheduler) ────────────────────────────────────────────────
+
+// Windows용 node 탐색 래퍼 PowerShell 스크립트 경로 (~/.tokenphage/run-sync.ps1).
+function ps1Path() {
+  return join(homedir(), '.tokenphage', 'run-sync.ps1');
+}
+
+// 구버전이 만들던 배치 래퍼 — uninstall 시 함께 정리해 잔여물을 남기지 않는다.
+function legacyBatPath() {
+  return join(homedir(), '.tokenphage', 'run-sync.bat');
+}
+
+// schtasks가 작업을 실행할 때의 PATH는 대화형 셸과 달리 제한적이라, 설치 시점
+// node 경로를 박아두면 nvm-windows/fnm/volta로 버전을 바꾸는 순간 조용히 깨진다.
+// 그래서 macOS 래퍼(buildSyncShellScript)와 동일하게, 실행 시점에 node를 동적
+// 탐색하는 PowerShell 래퍼를 거치게 한다. PowerShell은 유니코드에 안전하고(한글
+// 홈 경로 mojibake 방지) cmd 메타문자 파싱 문제도 없다.
+export function buildSyncPs1(script, logPath) {
+  const body = `# tokenphage auto-sync launcher — generated by tokenphage-cli.
+# node 바이너리를 실행 시점에 탐색한다 (nvm-windows / fnm / volta 변경에도 견고).
+
+$SCRIPT = ${psSingleQuote(script)}
+$LOG    = ${psSingleQuote(logPath)}
+
+# 주어진 루트 하위 디렉터리를 버전 내림차순으로 훑어 첫 node.exe 경로를 반환한다.
+function Get-NewestNodeIn($root, $relative) {
+  if (-not (Test-Path -LiteralPath $root)) { return $null }
+  $dirs = Get-ChildItem -LiteralPath $root -Directory -ErrorAction SilentlyContinue |
+    Sort-Object -Property @{ Expression = { try { [version]($_.Name.TrimStart('v')) } catch { [version]'0.0.0' } } } -Descending
+  foreach ($d in $dirs) {
+    $candidate = Join-Path $d.FullName $relative
+    if (Test-Path -LiteralPath $candidate) { return $candidate }
+  }
+  return $null
+}
+
+function Resolve-Node {
+  # 1) PATH 상의 node — 가장 권위 있고 대부분의 경우 여기서 끝난다.
+  $cmd = Get-Command node -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1
+  if ($cmd) { return $cmd.Source }
+
+  # 2) nvm-windows: 심링크 디렉터리 + 버전 설치 루트.
+  $nvmRoots = @($env:NVM_SYMLINK, $env:NVM_HOME, (Join-Path $env:APPDATA 'nvm'), 'C:\\nvm4w', 'C:\\nvm')
+  foreach ($r in $nvmRoots) {
+    if (-not $r) { continue }
+    $direct = Join-Path $r 'node.exe'
+    if (Test-Path -LiteralPath $direct) { return $direct }
+    $found = Get-NewestNodeIn $r 'node.exe'
+    if ($found) { return $found }
+  }
+
+  # 3) fnm: 정적 PATH 항목이 없어 PATH 폴백으로는 절대 못 잡는 핵심 케이스.
+  $fnmRoots = @($env:FNM_DIR, (Join-Path $env:USERPROFILE '.fnm'), (Join-Path $env:APPDATA 'fnm'), (Join-Path $env:LOCALAPPDATA 'fnm'))
+  foreach ($r in $fnmRoots) {
+    if (-not $r) { continue }
+    $found = Get-NewestNodeIn (Join-Path $r 'node-versions') 'installation\\node.exe'
+    if ($found) { return $found }
+  }
+
+  # 4) volta: shim 디렉터리의 node.exe.
+  $voltaBases = @($env:VOLTA_HOME, (Join-Path $env:USERPROFILE '.volta'), (Join-Path $env:ProgramFiles 'Volta'))
+  foreach ($b in $voltaBases) {
+    if (-not $b) { continue }
+    $candidate = Join-Path $b 'bin\\node.exe'
+    if (Test-Path -LiteralPath $candidate) { return $candidate }
+  }
+
+  # 5) 표준 설치 경로 (공식 설치본 / scoop / chocolatey).
+  $pf86 = [Environment]::GetEnvironmentVariable('ProgramFiles(x86)')
+  $standard = @()
+  if ($env:ProgramFiles)      { $standard += (Join-Path $env:ProgramFiles 'nodejs\\node.exe') }
+  if ($pf86)                  { $standard += (Join-Path $pf86 'nodejs\\node.exe') }
+  if ($env:USERPROFILE)       { $standard += (Join-Path $env:USERPROFILE 'scoop\\shims\\node.exe') }
+  if ($env:ChocolateyInstall) { $standard += (Join-Path $env:ChocolateyInstall 'bin\\node.exe') }
+  $standard += 'C:\\ProgramData\\chocolatey\\bin\\node.exe'
+  foreach ($s in $standard) {
+    if (Test-Path -LiteralPath $s) { return $s }
+  }
+
+  return $null
+}
+
+$node = Resolve-Node
+if (-not $node) {
+  Add-Content -LiteralPath $LOG -Value 'tokenphage: node 바이너리를 찾지 못했습니다 (PATH / nvm / fnm / volta 확인)'
+  [Console]::Error.WriteLine('tokenphage: node not found')
+  exit 127
+}
+if (-not (Test-Path -LiteralPath $SCRIPT)) {
+  Add-Content -LiteralPath $LOG -Value ('tokenphage: sync 스크립트를 찾지 못했습니다: ' + $SCRIPT)
+  exit 127
+}
+
+# 해석된 node의 디렉터리를 PATH 앞에 붙여 자식 프로세스도 같은 node를 쓰게 한다.
+$env:Path = (Split-Path -Parent $node) + ';' + $env:Path
+
+& $node $SCRIPT sync *>> $LOG
+exit $LASTEXITCODE
+`;
+  // PowerShell은 LF/CRLF 모두 읽지만 Windows 관례에 맞춰 CRLF로 통일한다.
+  return body.replace(/\r?\n/g, '\r\n');
+}
+
+// schtasks /XML에 넘길 작업 정의. Exec는 powershell.exe로 위 래퍼를 호출한다.
+// powershell.exe(Windows PowerShell 5.1)는 System32에 상시 존재해 제한 PATH에서도
+// 잡히므로 절대경로 대신 이름만 쓴다. StartBoundary는 과거 날짜 하드코딩 대신
+// 호출 시점(now) 기준으로 만들어 테스트 가능한 순수 함수로 유지한다.
+export function buildTaskXml(ps1FilePath, now = new Date()) {
+  const pad = (n) => String(n).padStart(2, '0');
+  const start =
+    `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}` +
+    `T${pad(SCHEDULE_HOUR)}:${pad(SCHEDULE_MINUTE)}:00`;
+  const psArgs = `-NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File "${ps1FilePath}"`;
+  return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>tokenphage daily sync (managed by tokenphage-cli)</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <CalendarTrigger>
+      <StartBoundary>${start}</StartBoundary>
+      <Enabled>true</Enabled>
+      <ScheduleByDay>
+        <DaysInterval>1</DaysInterval>
+      </ScheduleByDay>
+    </CalendarTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>true</RunOnlyIfNetworkAvailable>
+    <ExecutionTimeLimit>PT10M</ExecutionTimeLimit>
+    <Enabled>true</Enabled>
+    <Hidden>true</Hidden>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <WakeToRun>false</WakeToRun>
+    <Priority>7</Priority>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>powershell.exe</Command>
+      <Arguments>${escapeXml(psArgs)}</Arguments>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+
+// Windows 설치: PS1 래퍼(UTF-8 BOM) 작성 → Task XML(UTF-16 BOM) 생성 → schtasks /Create /F(멱등).
+// 권한 거부 시 관리자 터미널 안내와 함께 throw한다.
+function installWindows() {
+  const { script } = resolveTokenphageBinary();
+  const logPath = ensureLogDir();
+  const ps1 = ps1Path();
+  mkdirSync(join(homedir(), '.tokenphage'), { recursive: true });
+
+  // node 탐색 래퍼를 먼저 깔고, 작업이 이 래퍼를 가리키게 한다.
+  // UTF-8 BOM()으로 기록해야 PowerShell 5.1이 비ASCII 경로를 올바로 파싱한다.
+  writeFileSync(ps1, '' + buildSyncPs1(script, logPath), 'utf8');
+
+  // schtasks /XML은 UTF-16 BOM을 요구한다.
+  const xmlPath = join(tmpdir(), `tokenphage-task-${Date.now()}.xml`);
+  const xmlBody = buildTaskXml(ps1);
+  const buf = Buffer.concat([Buffer.from([0xFF, 0xFE]), Buffer.from(xmlBody, 'utf16le')]);
+  writeFileSync(xmlPath, buf);
+
+  try {
+    // idempotent: /F 로 기존 작업(레거시 .bat 기반 포함)을 덮어쓴다.
+    execFileSync('schtasks', ['/Create', '/TN', WIN_TASK_NAME, '/XML', xmlPath, '/F'], { stdio: 'pipe' });
+  } catch (err) {
+    const msg = (err.stderr?.toString() || err.message || '').trim();
+    if (/access is denied|액세스가 거부|0x80070005|requires elevation/i.test(msg)) {
+      throw new Error(
+        'schtasks 작업 등록이 거부되었습니다. 관리자 권한 터미널에서 다시 실행하세요.\n' +
+        'schtasks registration was denied — run this command from an elevated (Administrator) terminal.');
+    }
+    throw new Error(`schtasks registration failed: ${msg}`);
+  } finally {
+    try { unlinkSync(xmlPath); } catch { /* noop */ }
+  }
+
+  return {
+    platform: 'win32',
+    method: 'schtasks',
+    logPath,
+    scheduleSpec: `daily ${String(SCHEDULE_HOUR).padStart(2, '0')}:${String(SCHEDULE_MINUTE).padStart(2, '0')}`,
+    artifactPath: WIN_TASK_NAME,
+  };
+}
+
+// Windows 제거: schtasks /Delete 후 현재(.ps1)·레거시(.bat) 래퍼를 정리한다. removed 여부를 반환.
+function uninstallWindows() {
+  let removed = false;
+  try {
+    execFileSync('schtasks', ['/Delete', '/TN', WIN_TASK_NAME, '/F'], { stdio: 'ignore' });
+    removed = true;
+  } catch { /* 작업이 없으면 무시 */ }
+
+  // 현재 래퍼(.ps1)와 구버전 래퍼(.bat)를 모두 정리한다.
+  for (const p of [ps1Path(), legacyBatPath()]) {
+    if (existsSync(p)) {
+      try { unlinkSync(p); removed = true; } catch { /* noop */ }
+    }
+  }
+  return { platform: 'win32', removed };
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/** 현재 OS에 맞는 자동 sync 스케줄을 설치한다 (macOS=launchd / Windows=schtasks). 그 외 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.`);
+}
+
+/** 현재 OS의 자동 sync 스케줄을 제거한다 (macOS=launchd / Windows=schtasks). 그 외 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.`);
+}

package/src/sync.js

@@ -0,0 +1,36 @@
+/**
+ * 집계된 토큰 사용 기록을 서버에 업로드한다 (POST /api/sync).
+ * 사용자는 서버가 JWT(Bearer)에서 식별하고, 본문에 deviceId와 records를 담아 보낸다.
+ * @param {string} apiBase  API 서버 base URL
+ * @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
+ */
+export async function syncRecords(apiBase, token, deviceId, records) {
+  // Node 18+ 전역 fetch 사용 (node-fetch 의존성 불필요).
+  const res = await fetch(`${apiBase}/api/sync`, {
+    method: 'POST',
+    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()}`);
+}
+
+/**
+ * 서버에 전체 초기화를 요청한다. 대상은 서버가 JWT에서 식별하므로 본문은 비운다.
+ * @param {string} apiBase
+ * @param {string} token  Bearer JWT
+ */
+export async function resetData(apiBase, token) {
+  const res = await fetch(`${apiBase}/api/reset`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${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}`);
+  }
+}