@sejuneoh/aitop 0.0.0-stage → 0.21.1

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@sejuneoh/aitop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.21.1",
+  "description": "터미널에서 Claude Code · Codex · Antigravity · Gemini 세션과 토큰을 실시간으로 보는 읽기 전용 모니터",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "aitop": "bin/aitop.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "os": [
+    "linux",
+    "darwin"
+  ],
+  "homepage": "https://github.com/SejuneOh/aitop#readme",
+  "bugs": "https://github.com/SejuneOh/aitop/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SejuneOh/aitop.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node bin/aitop.mjs",
+    "test": "node --test test/*.test.mjs",
+    "test:e2e": "node --test test/e2e/*.e2e.mjs"
+  }
+}

package/src/attention.mjs

@@ -0,0 +1,70 @@
+// "끝났는데 아직 안 본" 세션 추적. aitop 메모리에만 두고 파일에는 쓰지 않는다.
+// 작업 중(busy·shell)이던 세션이 대기(idle)로 바뀌었는데 그때 선택돼 있지 않았으면 확인 전으로 본다.
+
+export function createAttention() {
+  return { prev: new Map(), unseen: new Set() };
+}
+
+export function updateAttention(state, sessions, selectedId) {
+  const ids = new Set();
+  for (const s of sessions) {
+    ids.add(s.id);
+    const before = state.prev.get(s.id);
+    // 상태를 기록 수정 시각으로 추측한 세션(statusGuessed)은, 작업이 아닌 줄이 붙어도 잠깐 작업 중으로 보이므로 확인 전으로 치지 않는다.
+    if (s.id === selectedId || s.status === 'busy' || s.status === 'shell' || !s.live) state.unseen.delete(s.id);
+    else if ((before === 'busy' || before === 'shell') && s.status === 'idle' && !s.statusGuessed) state.unseen.add(s.id);
+    state.prev.set(s.id, s.status);
+  }
+  for (const id of state.prev.keys()) if (!ids.has(id)) state.prev.delete(id);
+  for (const id of state.unseen) if (!ids.has(id)) state.unseen.delete(id);
+}
+
+export function markSeen(state, id) {
+  state.unseen.delete(id);
+}
+
+// 다음에 봐야 할 세션: 지금 선택한 세션은 빼고, 그 다음 것부터 한 바퀴 돌며 응답 대기 → 확인 전 순서로 찾는다.
+// 선택이 목록에 없으면(검색으로 가려짐 등) 맨 위부터 찾는다.
+export function nextAttention(state, sessions, selectedId) {
+  const at = sessions.findIndex((s) => s.id === selectedId);
+  const ordered = at < 0 ? sessions : [...sessions.slice(at + 1), ...sessions.slice(0, at)];
+  return ordered.find((s) => s.status === 'waiting') ?? ordered.find((s) => state.unseen.has(s.id)) ?? null;
+}
+
+// 응답 대기(◆)와 확인 전(●) 수.
+export function attentionCounts(sessions) {
+  return { waiting: sessions.filter((s) => s.live && s.status === 'waiting').length, unseen: sessions.filter((s) => s.unseen).length };
+}
+
+// 창 제목: 맨 앞 아이콘(탭 사이에서 aitop 을 찾게) + 응답 대기·확인 전 수. 예: 󰚩 (2◆ 1●) aitop
+export function windowTitle(sessions, icon = '') {
+  const { waiting, unseen } = attentionCounts(sessions);
+  const marks = [waiting && `${waiting}◆`, unseen && `${unseen}●`].filter(Boolean);
+  return (icon ? icon + ' ' : '') + (marks.length ? `(${marks.join(' ')}) aitop` : 'aitop');
+}
+
+// 새로 응답 대기가 된 세션 목록. seen 은 지난번 응답 대기 세션 id 집합이며 여기서 갱신한다.
+export function freshWaiting(seen, sessions) {
+  const now = sessions.filter((s) => s.live && s.status === 'waiting');
+  const fresh = now.filter((s) => !seen.has(s.id));
+  seen.clear();
+  for (const s of now) seen.add(s.id);
+  return fresh;
+}
+
+// 벨: 새로 응답 대기가 된 세션이 있을 때만 true.
+export function newlyWaiting(seen, sessions) {
+  return freshWaiting(seen, sessions).length > 0;
+}
+
+// --bell · --notify · --on-waiting 이 함께 쓰는 감시. 첫 갱신에서 이미 응답 대기인 세션은 알리지 않는다.
+export function createWaitWatch() {
+  return { seen: new Set(), ready: false };
+}
+
+export function takeNewlyWaiting(watch, sessions) {
+  const fresh = freshWaiting(watch.seen, sessions);
+  const ready = watch.ready;
+  watch.ready = true;
+  return ready ? fresh : [];
+}

package/src/brand.mjs

@@ -0,0 +1,30 @@
+// aitop 표식: 로고, 창·탭 아이콘, WezTerm 탭용 user var.
+// AITOP_ICONS 로 고른다.
+//   (없음)  로고 ⣠⣴⣾, 탭 아이콘은 Nerd Font 로봇(U+F06A9), WezTerm user var 를 내보낸다
+//   plain   Nerd 아이콘과 user var 를 끈다. 탭 아이콘은 로고의 마지막 막대 ⣾
+//   ascii   로고를 >_ai 로, 탭 아이콘 없음, user var 없음 (점자를 못 그리는 환경용)
+// 로고의 점자 글자는 동아시아 폭이 N 이라 한글 터미널에서도 늘 1칸이다.
+
+export function iconMode(env = process.env) {
+  return env.AITOP_ICONS === 'plain' || env.AITOP_ICONS === 'ascii' ? env.AITOP_ICONS : 'full';
+}
+
+export function brand(mode = iconMode()) {
+  if (mode === 'ascii') return { mode, logo: '>_ai', tab: '', userVars: false };
+  return {
+    mode,
+    logo: '⣠⣴⣾',
+    tab: mode === 'plain' ? '⣾' : '\u{F06A9}',
+    userVars: mode === 'full',
+  };
+}
+
+export const BRAND = brand();
+
+// WezTerm 탭 제목(format-tab-title)에서 pane.user_vars 로 읽는 값. 다른 터미널은 모르는 OSC 를 무시한다.
+// counts 가 null 이면 값을 지운다 (aitop 을 끝낼 때).
+export function userVarsSeq(counts) {
+  const set = (name, value) => `\x1b]1337;SetUserVar=${name}=${Buffer.from(value).toString('base64')}\x07`;
+  if (!counts) return set('aitop', '') + set('aitop_waiting', '') + set('aitop_unseen', '');
+  return set('aitop', '1') + set('aitop_waiting', String(counts.waiting)) + set('aitop_unseen', String(counts.unseen));
+}

package/src/budget.mjs

@@ -0,0 +1,29 @@
+// 하루 예산(budgetDay): 오늘 비용에 최근 지출 속도 × 로컬 자정까지 남은 시간을 더해 오늘 끝의 비용을 어림한다.
+// 예산은 화면의 비용 기준(c 키)과 상관없이 늘 API 정가 환산으로 본다. 그래서 화면과 --json 의 단계가 같다.
+// 예상이 예산의 CAUTION 배 이상이면 'caution', 예산 이상이면 'warn'.
+
+export const CAUTION = 0.8;
+// 자정 뒤 이만큼이 지나기 전에는 속도를 믿지 않고 예상 = 오늘 비용.
+export const MIN_TODAY_MS = 15 * 60_000;
+
+// 지금부터 로컬 자정까지 남은 시간 (시간 단위).
+export function hoursToMidnight(now = Date.now()) {
+  const d = new Date(now);
+  const midnight = new Date(d.getFullYear(), d.getMonth(), d.getDate() + 1).getTime();
+  return Math.max(0, (midnight - now) / 3600_000);
+}
+
+export const levelOf = (projected, day) => (projected >= day ? 'warn' : projected >= day * CAUTION ? 'caution' : 'ok');
+
+// usage: collect 의 사용량. recentToday 는 최근 1시간 중 오늘(로컬 자정 이후) 몫과 그 구간 길이(ms)다 (recentTodayOf).
+// 속도 = 그 몫을 시간당으로 늘린 값. 값이 없거나, 아직 집계 중이거나, 자정 뒤 15분이 안 됐으면 예상 = 오늘 비용.
+// 예산이 없거나 사용량이 없으면 null.
+export function projectBudget(usage, day, { now = Date.now() } = {}) {
+  if (!(typeof day === 'number' && day > 0) || !usage?.today) return null;
+  const r = usage.loading == null && usage.recentToday?.ms >= MIN_TODAY_MS ? usage.recentToday : null;
+  const spent = usage.today.cost ?? 0;
+  const perHour = r ? (r.cost ?? 0) / (r.ms / 3600_000) : 0;
+  const projected = spent + perHour * hoursToMidnight(now);
+  const unknown = Boolean(usage.today.unknown || r?.unknown);
+  return { day, spent, projected, unknown, level: levelOf(projected, day) };
+}

package/src/cache.mjs

@@ -0,0 +1,78 @@
+// 큰 세션 기록을 매번 처음부터 다시 읽지 않도록, 파일별로 "어디까지 읽었고 그때 합계가 얼마였는지"를
+// ~/.cache/aitop 에 저장한다. 이 프로그램이 디스크에 쓰는 곳은 여기와 --debug 때의 디버그 로그(log.mjs)뿐이다.
+import { readFileSync, writeFileSync, mkdirSync, renameSync, statSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { PRICE_TAG } from './pricing.mjs';
+import { debug, debugIo } from './log.mjs';
+
+// 캐시 형식이 바뀌면 VERSION 을, 가격표가 바뀌면 PRICE_TAG 가 폴더 이름을 바꿔서 예전 캐시를 버린다.
+const VERSION = 13;
+const ROOT = join(process.env.XDG_CACHE_HOME ?? join(homedir(), '.cache'), 'aitop');
+const NAME = `v${VERSION}-${PRICE_TAG}`;
+const DIR = join(ROOT, NAME);
+export const CACHE_DIR = DIR;
+const dirty = new Map();
+let cleaned = false;
+
+// 다른 버전의 aitop 이 같이 쓰고 있을 수 있으니, 같은 형식의 다른 폴더는 일주일 넘게 손대지 않았을 때만 지운다.
+const STALE_DIR_MS = 7 * 24 * 3600 * 1000;
+
+function removeOldDirs() {
+  cleaned = true;
+  try {
+    for (const d of readdirSync(ROOT)) {
+      if (d === NAME) continue;
+      const p = join(ROOT, d);
+      // 이 버전보다 낮은 형식(v2, v6-… 등)은 더 이상 어떤 버전도 쓰지 않으므로 바로 지운다.
+      const ver = Number(/^v(\d+)(?:-|$)/.exec(d)?.[1]);
+      if (ver < VERSION || Date.now() - statSync(p).mtimeMs > STALE_DIR_MS) rmSync(p, { recursive: true, force: true });
+    }
+  } catch (e) {
+    debugIo('cache', 'old cache cleanup failed', e);
+  }
+}
+
+// kind: 같은 기록 파일을 다른 용도로 읽는 tracker 가 각자 캐시를 갖도록 구분한다 (예: 세션 화면용, 날짜별 사용량용).
+const keyOf = (path, kind) => createHash('sha1').update(`${kind}\0${path}`).digest('hex');
+
+// 파일이 바뀌지 않고 뒤에만 붙었을 때(크기가 같거나 커졌고 inode 가 같을 때)만 캐시를 쓴다.
+export function loadCache(path, kind = '') {
+  try {
+    const c = JSON.parse(readFileSync(join(DIR, keyOf(path, kind) + '.json'), 'utf8'));
+    const st = statSync(path);
+    if (c.path !== path || c.ino !== st.ino || st.size < c.offset) return null;
+    return c;
+  } catch (e) {
+    debugIo('cache', 'cache load failed', e);
+    return null;
+  }
+}
+
+export function markDirty(path, snapshot, kind = '') {
+  dirty.set(keyOf(path, kind), { path, build: snapshot });
+}
+
+export function flushCache() {
+  if (!dirty.size) return;
+  try {
+    mkdirSync(DIR, { recursive: true, mode: 0o700 });
+  } catch (e) {
+    debug('cache', 'cache folder create failed', e);
+    return;
+  }
+  if (!cleaned) removeOldDirs();
+  for (const [key, { path, build }] of dirty) {
+    try {
+      const data = build();
+      if (!data) continue;
+      const file = join(DIR, key + '.json');
+      writeFileSync(file + '.tmp', JSON.stringify({ ...data, path, ino: statSync(path).ino }), { mode: 0o600 });
+      renameSync(file + '.tmp', file);
+    } catch (e) {
+      debugIo('cache', 'cache write failed', e);
+    }
+  }
+  dirty.clear();
+}

package/src/collect.mjs

@@ -0,0 +1,51 @@
+import { collectClaude } from './sources/claude.mjs';
+import { collectCodex } from './sources/codex.mjs';
+import { collectGemini } from './sources/gemini.mjs';
+import { collectAgy } from './sources/antigravity.mjs';
+import { collectLedger } from './sources/claude-ledger.mjs';
+import { createBudget } from './tail.mjs';
+
+const RANK = { waiting: 0, busy: 1, shell: 2, live: 3, idle: 4, ended: 5 };
+
+// 상태 순서가 먼저다. 같은 상태 안에서는 갱신마다 자리가 바뀌지 않도록 바뀌지 않는 값으로 줄 세운다:
+// 늦게 시작한 세션이 위, 시작 시각이 없으면 아래, 그다음 도구·id 순.
+// 종료 세션은 더 바뀌지 않으므로 최근에 끝난 세션이 위로 오게 마지막 활동 시각으로 줄 세운다.
+export function bySession(a, b) {
+  const at = (s) => (s.status === 'ended' ? s.updatedAt : s.startedAt) ?? -Infinity;
+  return (
+    (RANK[a.status] ?? 9) - (RANK[b.status] ?? 9) ||
+    at(b) - at(a) ||
+    String(a.tool ?? '').localeCompare(String(b.tool ?? '')) ||
+    String(a.id ?? '').localeCompare(String(b.id ?? ''))
+  );
+}
+
+// budgetBytes·budgetMs: 이번 갱신에서 세션 기록을 읽을 최대 바이트와 시간. 실시간 화면은 작게 잡아 큰 기록을 여러 번에 나눠 읽는다.
+// 돌려주는 more 가 true 면 한도 때문에 덜 읽은 기록이 있다.
+// 도구마다, 그리고 날짜별 사용량 장부에 한도를 따로 줘서 서로의 읽기를 막지 않게 한다.
+export function collect({ budgetBytes = Infinity, budgetMs = Infinity, ...opts } = {}) {
+  const budgets = [];
+  const budgetOf = (bytes, ms) => {
+    const b = createBudget(bytes, ms);
+    budgets.push(b);
+    return b;
+  };
+  const sessions = [];
+  const errors = [];
+  for (const [tool, fn] of [['claude', collectClaude], ['codex', collectCodex], ['gemini', collectGemini], ['agy', collectAgy]]) {
+    try {
+      sessions.push(...fn({ ...opts, budget: budgetOf(budgetBytes, budgetMs) }));
+    } catch (err) {
+      errors.push(`${tool}: ${err.message}`);
+    }
+  }
+  // 장부는 세션 화면보다 덜 급하니 한 번 갱신에 세션 한도의 1/3 만 읽는다 (처음 한 번 다 읽은 뒤에는 캐시와 새 줄만 읽는다).
+  let usage = null;
+  try {
+    usage = collectLedger({ budget: budgetOf(budgetBytes / 3, budgetMs / 2) });
+  } catch (err) {
+    errors.push(`usage: ${err.message}`);
+  }
+  sessions.sort(bySession);
+  return { sessions, usage, errors, at: Date.now(), more: budgets.some((b) => b.exhausted) };
+}

package/src/config.mjs

@@ -0,0 +1,169 @@
+// 설정: 옵션마다 명령줄 옵션(flag) > 환경 변수(env) > 설정 파일(file) > 기본값(default) 순서로 고른다.
+// 설정 파일은 $XDG_CONFIG_HOME/aitop/config.json (없으면 ~/.config/aitop/config.json). aitop 은 이 파일을 읽기만 한다.
+// 잘못된 JSON, 모르는 키, 잘못된 값은 그 키만 무시하고 problems 에 남긴다 (--doctor 와 --print-config 가 보인다).
+// 화면 모듈은 불러올 때 테마·아이콘을 고르므로, 이 모듈은 다른 aitop 모듈을 불러오지 않는다.
+import { closeSync, constants, fstatSync, openSync, readSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { stripControl } from './text.mjs';
+
+const bool = (v) => typeof v === 'boolean';
+const oneOf = (...xs) => (v) => xs.includes(v);
+// 달러 금액 글자("50", "12.5", "$50")를 0 보다 큰 수로 바꾼다. 아니면 null.
+const usd = (v) => {
+  const t = String(v).trim().replace(/^\$/, '');
+  const n = /^\d+(\.\d+)?$|^\.\d+$/.test(t) ? Number(t) : NaN;
+  return Number.isFinite(n) && n > 0 ? n : null;
+};
+
+// argv 에서 --budget-day <usd>, --budget-day=<usd>, --no-budget-day 를 꺼낸다. 뒤에 준 쪽을 따른다.
+// value: 금액, null(이번 실행만 끔), undefined(주지 않음). 나머지 인자는 rest 로 돌려준다.
+export function budgetDayOption(argv) {
+  let value;
+  let error = null;
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--no-budget-day') {
+      value = null;
+      continue;
+    }
+    const m = /^--budget-day(?:=(.*))?$/.exec(a);
+    if (!m) {
+      rest.push(a);
+      continue;
+    }
+    // 다음 인자가 옵션이면 값으로 먹지 않는다. -5 처럼 수로 보이면 값으로 받아 잘못된 값으로 알린다.
+    const next = argv[i + 1];
+    const raw = m[1] ?? (next == null || (next.startsWith('-') && !/^-[\d.]/.test(next)) ? '' : argv[++i]);
+    const n = usd(raw);
+    if (n == null) error ??= raw === '' ? '--budget-day 값이 없습니다 (하루 예산, 달러)' : `--budget-day 값 ${JSON.stringify(raw)} 이 잘못되었습니다 (0 보다 큰 수)`;
+    else value = n;
+  }
+  return { value, rest, error };
+}
+
+// env: 환경 변수 이름과 그 값을 옵션 값으로 바꾸는 함수 (undefined 면 설정하지 않은 것으로 본다).
+// envProblem: 환경 변수 값이 잘못되면 무시하고 problems 에 남긴다 (--doctor, --print-config 가 보인다).
+// notify, onWaiting 은 응답 대기 알림(notify.mjs)이 쓴다. debug 는 디버그 로그(log.mjs)를 켠다. budgetDay 는 하루 예산(달러)으로, 헤더와 --json 의 예상 비용 경고(budget.mjs)가 쓴다.
+export const KEYS = {
+  theme: { ok: oneOf('light', 'dark'), expect: 'light 또는 dark', def: null, env: ['AITOP_THEME', (v) => (v === 'light' || v === 'dark' ? v : undefined)] },
+  icons: { ok: oneOf('plain', 'ascii'), expect: 'plain 또는 ascii', def: 'full', env: ['AITOP_ICONS', (v) => (v === 'plain' || v === 'ascii' ? v : undefined)] },
+  bell: { ok: bool, expect: 'true 또는 false', def: false },
+  showRequests: { ok: bool, expect: 'true 또는 false', def: false, env: ['AITOP_SHOW_REQUESTS', (v) => (v === '1' ? true : v === '0' ? false : undefined)] },
+  all: { ok: bool, expect: 'true 또는 false', def: false },
+  notify: { ok: bool, expect: 'true 또는 false', def: false },
+  onWaiting: { ok: (v) => typeof v === 'string' && v.trim() !== '', expect: '실행할 명령 문자열', def: null },
+  debug: { ok: bool, expect: 'true 또는 false', def: false, env: ['AITOP_DEBUG', (v) => (v === '1' ? true : v === '0' ? false : undefined)], envProblem: true, envExpect: '1 또는 0' },
+  budgetDay: { ok: (v) => typeof v === 'number' && Number.isFinite(v) && v > 0, expect: '0 보다 큰 수', def: null, env: ['AITOP_BUDGET_DAY', (v) => usd(v) ?? undefined], envProblem: true },
+  // colorBlind 는 적록 색약 팔레트(ui/theme.mjs)를 고른다. theme(밝기)과 따로 정한다.
+  colorBlind: { ok: bool, expect: 'true 또는 false', def: false, env: ['AITOP_COLOR_BLIND', (v) => (v === '1' ? true : v === '0' ? false : undefined)], envProblem: true, envExpect: '1 또는 0' },
+  // 실행 중 세션이 없고 7일 동안 쓰지 않은 도구를 도구 줄에서 숨긴다. false 면 늘 셋 다 보인다.
+  hideIdleTools: { ok: bool, expect: 'true 또는 false', def: true },
+  // 폭이 모호한 기호(·, →, ─, ● 등)를 2칸으로 그리는 터미널이면 wide. 표 칸이 밀리지 않게 1칸 기호로 바꾸고 폭을 2칸으로 센다.
+  ambiguous: { ok: oneOf('narrow', 'wide'), expect: 'narrow 또는 wide', def: 'narrow', env: ['AITOP_AMBIGUOUS', (v) => (v === 'narrow' || v === 'wide' ? v : undefined)], envProblem: true },
+};
+
+export function configPath(env = process.env, home = homedir()) {
+  const xdg = env.XDG_CONFIG_HOME;
+  return join(xdg && isAbsolute(xdg) ? xdg : join(home, '.config'), 'aitop', 'config.json');
+}
+
+// 설정 파일은 작다. 이보다 크면 읽지 않는다.
+export const MAX_BYTES = 64 * 1024;
+
+const show = (v) => JSON.stringify(v)?.slice(0, 60) ?? String(v);
+
+// 파일을 읽어 올바른 키만 values 에 담는다. uid: 현재 사용자 (테스트에서 바꿔 끼운다).
+export function readConfigFile(path, { uid = process.getuid?.() } = {}) {
+  const res = { path, exists: false, values: {}, problems: [] };
+  let fd;
+  let text;
+  let st;
+  const notFile = () => res.problems.push('설정 파일이 일반 파일이 아니라 읽지 않습니다');
+  const tooBig = () => res.problems.push(`설정 파일이 ${MAX_BYTES / 1024}KB 를 넘어 읽지 않습니다`);
+  try {
+    // FIFO 나 장치 파일을 열면 멈출 수 있으므로 열기 전에 확인하고, 열 때도 기다리지 않게 연다.
+    st = statSync(path);
+    res.exists = true;
+    if (!st.isFile()) return (notFile(), res);
+    if (st.size > MAX_BYTES) return (tooBig(), res);
+    fd = openSync(path, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+    st = fstatSync(fd);
+    if (!st.isFile()) return (notFile(), res);
+    if (st.size > MAX_BYTES) return (tooBig(), res);
+    // 확인한 뒤에 파일이 커져도 한도 + 1 바이트까지만 읽는다.
+    const buf = Buffer.alloc(MAX_BYTES + 1);
+    let n = 0;
+    for (let got; n < buf.length && (got = readSync(fd, buf, n, buf.length - n, n)) > 0; ) n += got;
+    if (n > MAX_BYTES) return (tooBig(), res);
+    text = buf.subarray(0, n).toString('utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      res.exists = err.code !== 'ENOTDIR';
+      res.problems.push(`설정 파일을 읽을 수 없습니다 (${err.code ?? err.message})`);
+    }
+    return res;
+  } finally {
+    if (fd != null) closeSync(fd);
+  }
+  let obj;
+  try {
+    obj = JSON.parse(text);
+  } catch (err) {
+    // 오류 문구에 파일 내용 일부가 들어가므로 제어문자를 지우고 줄인다.
+    res.problems.push(`설정 파일이 올바른 JSON 이 아니라 무시합니다 (${stripControl(err.message).slice(0, 120)})`);
+    return res;
+  }
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+    res.problems.push('설정 파일의 맨 위는 JSON 객체({ ... })여야 합니다');
+    return res;
+  }
+  for (const [key, value] of Object.entries(obj)) {
+    const spec = Object.hasOwn(KEYS, key) ? KEYS[key] : null;
+    if (!spec) res.problems.push(`모르는 키 ${show(key)} 는 무시합니다`);
+    else if (!spec.ok(value)) res.problems.push(`${key} 값 ${show(value)} 이 잘못되어 무시합니다 (${spec.expect})`);
+    else res.values[key] = value;
+  }
+  // 응답 대기 때 실행할 명령은 다른 사용자가 바꿀 수 없는 파일에서만 받는다.
+  if ('onWaiting' in res.values) {
+    const mine = uid == null || st.uid === uid;
+    const shared = (st.mode & 0o022) !== 0;
+    if (!mine || shared) {
+      delete res.values.onWaiting;
+      const why = [!mine && '파일 소유자가 현재 사용자가 아님', shared && `그룹·다른 사용자가 쓸 수 있음 (mode ${(st.mode & 0o777).toString(8).padStart(3, '0')})`].filter(Boolean).join(', ');
+      res.problems.push(`onWaiting 은 무시합니다: ${why}. chmod 600 으로 고치세요`);
+    }
+  }
+  return res;
+}
+
+// flags: 명령줄에서 정한 값만 담는다 (주지 않은 옵션은 넣지 않는다).
+export function resolveConfig({ flags = {}, env = process.env, file } = {}) {
+  file ??= readConfigFile(configPath(env));
+  const values = {};
+  const problems = [...file.problems];
+  for (const [key, spec] of Object.entries(KEYS)) {
+    const fromEnv = spec.env && env[spec.env[0]] != null ? spec.env[1](env[spec.env[0]]) : undefined;
+    if (spec.envProblem && env[spec.env[0]] != null && fromEnv === undefined) problems.push(`환경 변수 ${spec.env[0]} 값 ${show(env[spec.env[0]])} 이 잘못되어 무시합니다 (${spec.envExpect ?? spec.expect})`);
+    if (flags[key] !== undefined) values[key] = { value: flags[key], source: 'flag' };
+    else if (fromEnv !== undefined) values[key] = { value: fromEnv, source: 'env' };
+    else if (key in file.values) values[key] = { value: file.values[key], source: 'file' };
+    else values[key] = { value: spec.def, source: 'default' };
+  }
+  return { path: file.path, exists: file.exists, values, problems };
+}
+
+// --print-config 의 사람용 출력.
+export function configText(cfg) {
+  const out = [`설정 파일: ${stripControl(cfg.path)} (${cfg.exists ? '있음' : '없음'})`, ''];
+  for (const [key, { value, source }] of Object.entries(cfg.values)) {
+    const v = value == null ? (key === 'theme' ? 'auto' : '-') : typeof value === 'string' ? JSON.stringify(value) : String(value);
+    out.push(`${key.padEnd(14)}${v.padEnd(12)} ${source}`);
+  }
+  if (cfg.problems.length) out.push('', ...cfg.problems.map((p) => `! ${stripControl(p)}`));
+  return out.join('\n');
+}
+
+// --print-config --json, --doctor --json 용.
+export const configJson = (cfg) => ({ path: cfg.path, exists: cfg.exists, values: cfg.values, problems: cfg.problems });