cc-usage-bar 0.1.0 → 0.4.1

package/AGENTS.md

@@ -0,0 +1,233 @@
+# AGENTS.md — cc-usage-bar 全功能说明
+
+> 这份文件是面向 AI 助手（Claude Code、Cursor、Codex 等）的安装/配置说明。如果用户对你说「装 cc-usage-bar」「帮我配 statusline 用量条」「装下 cc-usage-bar 帮我配好」之类的话，请按本文档完成全部步骤。**默认无需向用户追加确认**；只有用户没登录过 Claude Code（凭证查不到）时才停下来让用户先登录。
+
+## 1. 这个包是什么
+
+`cc-usage-bar` 把 Claude Code 订阅用量（5 小时滑窗 + 7 天滑窗）渲染到 statusline。也支持余额型 provider（Kimi / GLM / MiniMax / DeepSeek / StepFun / SiliconFlow / OpenRouter / Novita）。
+
+**核心 bin**：
+
+| bin | 用途 |
+|---|---|
+| `cc-usage-fetch` | 单纯渲染一段用量字符串到 stdout（最常用） |
+| `cc-usage-bar-wrap` | 跨平台编排器：tee stdin 给「前缀命令」+ `cc-usage-fetch`，按真实终端宽度自动单行/换行 |
+| `cc-usage-bar` / `cc-usage-statusline` | 安装器（自动改 settings.json），带 `agents`/`install`/`uninstall`/`status` 子命令 |
+
+## 2. 一句话目标
+
+> **用户只描述偏好，你把 `statusLine.command` 配成 `cc-usage-bar-wrap`，并保留用户原有前缀。**
+
+如果已有 `statusLine.command`、`statusline-command.sh`、自定义 shell 脚本、git/path/model 展示等前缀内容，**一律视为要保留的前缀**：按 3.4 抽出它，并用 `cc-usage-bar-wrap --prefix=...` 串起来。不要询问是否覆盖、追加或暂不修改；追加保留是本项目默认行为。
+
+## 3. 安装流程（必走）
+
+按顺序执行，每一步执行前简要告知用户：
+
+### 3.1 判断平台
+
+```js
+node -e "console.log(process.platform)"
+// → "darwin" | "linux" | "win32"
+```
+
+### 3.2 安装 npm 包
+
+```sh
+npm i -g cc-usage-bar
+# 验证（macOS/Linux）
+which cc-usage-bar-wrap && which cc-usage-fetch
+# 验证（Windows）
+where.exe cc-usage-bar-wrap
+```
+
+要求：`cc-usage-bar` ≥ **0.4.1**（自适应换行 + 周限额上色 + countdown 预设 + 颜色 ramp 自定义 + tint reverse 样式）。已装旧版的话用 `npm i -g cc-usage-bar@latest` 升级。
+
+### 3.3 读取现有 statusLine.command
+
+- **macOS / Linux**：`~/.claude/settings.json`，字段 `statusLine.command`
+- **Windows**：`%USERPROFILE%\.claude\settings.json` 同上
+
+不存在或为空 → 视为「无前缀」。
+
+### 3.4 剥离旧的 cc-usage-fetch / cc-usage-bar-wrap
+
+如果原命令包含 `cc-usage-fetch` 或 `cc-usage-bar-wrap` 字样，**先剥掉那部分**，剩下的才是用户真正的前缀脚本（可能是 `sh ~/.claude/statusline-command.sh` 这种）。常见模式：
+
+```
+sh -c '<前缀脚本>; printf " "; cc-usage-fetch ...'
+```
+要把 `<前缀脚本>` 抽出来作为新的 `--prefix=`。
+
+### 3.5 备份 settings.json
+
+- macOS/Linux：`cp ~/.claude/settings.json ~/.claude/settings.json.bak.$(date +%s)`
+- Windows：`Copy-Item $env:USERPROFILE\.claude\settings.json "$env:USERPROFILE\.claude\settings.json.bak.$([DateTimeOffset]::Now.ToUnixTimeSeconds())"`
+
+### 3.6 写回 statusLine.command
+
+**保留 settings.json 其它字段不动**，只更新这一项；`refreshInterval: 30`。
+
+| 情况 | 新 command |
+|---|---|
+| 有前缀脚本 | `cc-usage-bar-wrap --prefix='<前缀>' --format=bar-countdown` |
+| 无前缀（只显示用量条） | `cc-usage-fetch --format=bar-countdown` |
+
+`bar-countdown` 是 v0.4.0 起的默认预设（既显示进度条又显示倒计时）。如果用户偏好旧风格，把它换成 `--format=bar-time`、`--format=bar`、`--format=compact` 即可。
+
+**关键禁忌**：
+
+- ❌ 不要再写 `sh -c '...'` 包裹 `cc-usage-bar-wrap` —— wrap 内部已处理 stdin tee + 子进程 + 自适应换行。
+- ❌ 前缀脚本结尾不能有多余 `printf "\n"`（会让用量条挤到第二行被裁剪，wrap 会自己 trim 但仍最好清掉）。
+- ❌ Windows cmd 里单引号无效，前缀有特殊字符时改用双引号 + 反斜杠转义，或用环境变量 `CC_STATUSLINE_PREFIX` 喂给 wrap。
+
+### 3.7 自检
+
+跑一次假数据：
+
+```sh
+echo '{"workspace":{"current_dir":"."},"model":{"display_name":"Opus"}}' \
+  | cc-usage-bar-wrap --prefix='<原前缀>' --layout=single --format=bar-time
+```
+
+输出应包含 `[`、`█`、`░` 等字符。报 `No Claude Code credentials found` 时让用户先 `claude` 登录一次。
+
+## 4. 自适应换行
+
+`cc-usage-bar-wrap` 默认 `--layout=auto`：
+
+- 通过 `stty size </dev/tty`（Unix）或 `mode con`（Windows）拿真实终端列数
+- 剥 ANSI 数字符（UTF-8 字符数，不是字节数）
+- 单行能装下 → `prefix bar`；装不下 → `prefix\nbar`
+- 拿不到列数 → 回退多行（最安全）
+
+强制行为：
+
+```sh
+cc-usage-bar-wrap --layout=single   # 永远单行
+cc-usage-bar-wrap --layout=multi    # 永远换行
+# 或用环境变量
+CC_STATUSLINE_LAYOUT=single
+```
+
+## 5. 风格预设（`--format`）
+
+| 预设 | 渲染 |
+|---|---|
+| `compact`（默认） | `5h 47% Wk 59%` |
+| `numeric` | `47% / 59%` |
+| `time` | `47% until 18:23 / 59% until 5/12 09:00` |
+| `countdown` | `47% in 1h23m / 59% in 2d6h` |
+| `bar` | `[█████░░░░░] 47% / [██████░░░░] 59%` |
+| `bar-time` | `[█████░░░░░] 47% until 18:23 / [██████░░░░] 59% until 5/12 09:00` |
+| `bar-countdown` | `[█████░░░░░] 47% in 1h23m / [██████░░░░] 59% in 2d6h` |
+
+自定义模板（环境变量，覆盖 `--format`）：
+
+```sh
+CC_USAGE_TEMPLATE='{label} {percent}% ({countdown} left)'
+# 占位符: {label} {percent} {bar} {expiry} {countdown} {provider} {amount}
+```
+
+## 6. 颜色 ramp（5h / Wk / 余额各自可定制）
+
+默认（**v0.4.0 起 5h 和 Wk 都默认上色**）：
+
+| 区间 | 颜色 |
+|---|---|
+| 0–60% | `green` |
+| 60–85% | `yellow` |
+| 85–100% | `red` |
+
+环境变量覆盖：
+
+```sh
+# 5 小时窗口
+CC_USAGE_COLORS_5H='0:green,60:yellow,85:red'
+# 7 天窗口（可以更激进，比如临界变粗红）
+CC_USAGE_COLORS_WK='0:green,60:yellow,85:boldRed'
+# 余额型 provider
+CC_USAGE_COLORS_BALANCE='0:cyan,60:yellow,90:red'
+```
+
+格式：`<min>:<color>` 用逗号分隔，`min` 可以是小数。
+
+**颜色 token 三种形态**：
+
+| 类型 | 例 | 说明 |
+|---|---|---|
+| 命名色 | `red` `boldRed` `dim` 等 | 16 色调色板 + bold 变体 |
+| Hex | `#ff3333` `#fa0` | 24-bit truecolor，需要终端支持 |
+| `none` | `none` | 这一区间不上色 |
+
+完整命名色：`green` `yellow` `red` `blue` `magenta` `cyan` `white` `gray` `dim`、
+`boldGreen` `boldYellow` `boldRed` `boldBlue` `boldMagenta` `boldCyan` `boldWhite`。
+
+例：`CC_USAGE_COLORS_WK='0:#888888,50:#ffaa00,80:#ff3333,95:boldRed'`
+
+## 7. 进度条样式（`--bar-spec`，**5h 和 Wk 共用**）
+
+```sh
+# 自定义填充/空槽字符（cells）
+--bar-spec='{"mode":"cells","filled":"▰","empty":"▱","width":12}'
+
+# 单色渐变（tint）—— 完成部分上色，剩余部分变暗
+--bar-spec='{"mode":"tint","text":"████████","emptyStyle":"dim"}'
+
+# 反色填充（reverse）—— 完成部分用反色底块增强对比
+--bar-spec='{"mode":"tint","text":"Ciallo~(∠・ω< )⌒★","style":"reverse"}'
+
+# 动画帧（frames）—— 按百分比从帧序列里挑一帧
+--bar-spec='{"mode":"frames","frames":["⠋","⠙","⠹","⠸","⠼","⠴","⠦","⠧","⠇","⠏"]}'
+```
+
+环境变量 `CC_USAGE_BAR_SPEC` 同上。Windows cmd 里单引号无效，改 `"{\"mode\":...}"`。
+
+## 8. 凭证查找顺序
+
+| 平台 | 1 | 2 | 3 |
+|---|---|---|---|
+| macOS | 钥匙串 `Claude Code-credentials` | `~/.claude/.credentials.json` | — |
+| Windows | Credential Manager `Claude Code-credentials` | `%USERPROFILE%\.claude\.credentials.json` | — |
+| Linux | `~/.claude/.credentials.json` | — | — |
+
+非 Anthropic provider 用 `ANTHROPIC_AUTH_TOKEN` 环境变量。
+
+## 9. 缓存与请求节流
+
+- 成功结果缓存 30 秒（`/tmp/cc-oauth-usage.json` 或 OS tmpdir）
+- 鉴权失败缓存 60 秒
+- 限流（429）/ 5xx 缓存 60 秒（v0.3.0 起）—— 防止重试风暴
+- Claude Code 注入 stdin `rate_limits` 时直接用，**0 次** API 调用
+
+诊断：`CC_USAGE_LOG=/tmp/ccu.log` 让 `cc-usage-fetch` 每次写一行 JSON（`source` / `cacheStatus` / `error`）。
+
+## 10. 排障
+
+| 现象 | 处理 |
+|---|---|
+| `No Claude Code credentials found` | `claude` 登录一次 |
+| 用量条没颜色 | v0.3.x 之前 Wk 默认无色，升级到 0.4.0+ |
+| 窄屏被截 | 确认 statusLine.command 用的是 `cc-usage-bar-wrap`，不是直接 `cc-usage-fetch` |
+| 单行/换行不切换 | 确认 `--layout=auto`（默认），并确认环境里有 `/dev/tty`（Unix）或可用 console（Windows） |
+| Windows cmd 看不到颜色 | 换 Windows Terminal / PowerShell 7，或加 `--plain` |
+| 余额 provider 显示「No credits」 | 检查 `ANTHROPIC_AUTH_TOKEN` 是否对应该 provider |
+| settings.json 写坏 | `cp ~/.claude/settings.json.bak.<timestamp> ~/.claude/settings.json` |
+
+## 11. 完成后该说什么
+
+告诉用户：
+
+> ✅ 装好了。下次 statusline 刷新（≤ 30 秒）就能看到，不需要重启 Claude Code。试着拉宽 / 拉窄窗口，进度条会单行 ↔ 换行自动切换。
+
+## 12. 用户偏好默认值（用户没说就这么用）
+
+- `--format=bar-countdown`（v0.4.0 起的默认）
+- `--bar-width=10`
+- `--layout=auto`
+- 颜色保留，按默认 ramp（绿/黄/红）
+- 不加自定义 `--bar-spec`
+
+如用户说「极简」「窄屏」「我屏幕只有 80 列」→ 改 `--format=compact`。
+如用户说「我想看还剩多久」→ 改 `--format=countdown` 或 `--format=bar-countdown`。
+如用户说「Wk 颜色不一样」「Wk 紧迫的时候要更醒目」→ 设 `CC_USAGE_COLORS_WK='0:gray,80:boldRed'` 之类。

package/README.md

@@ -1,5 +1,11 @@
 # cc-usage-bar
 
+[![npm version](https://img.shields.io/npm/v/cc-usage-bar.svg)](https://www.npmjs.com/package/cc-usage-bar)
+[![npm downloads](https://img.shields.io/npm/dm/cc-usage-bar.svg)](https://www.npmjs.com/package/cc-usage-bar)
+[![license](https://img.shields.io/npm/l/cc-usage-bar.svg)](LICENSE)
+[![node](https://img.shields.io/node/v/cc-usage-bar.svg)](package.json)
+[![GitHub](https://img.shields.io/badge/GitHub-TuYv%2Fcc--usage--bar-181717?logo=github)](https://github.com/TuYv/cc-usage-bar)
+
 [中文说明](README.zh-CN.md)
 
 Show your Claude Code subscription usage in the statusline. Works with the official Anthropic subscription and 8 alternative providers (Kimi, GLM/Zhipu, MiniMax, DeepSeek, StepFun, SiliconFlow, OpenRouter, Novita).
@@ -43,7 +49,7 @@ A Claude Code statusline is just a shell command — its stdout is rendered to t
 
 1. **stdin `rate_limits`** — Claude Code now passes a `rate_limits` object to statusline stdin when you're a Claude.ai subscriber. Zero auth, zero network.
 2. **Local cache** — `/tmp/cc-oauth-usage.json`, 30 s TTL on success, 60 s on auth failure (so a stale token doesn't hammer the API).
-3. **Provider HTTP query** — picked from `ANTHROPIC_BASE_URL`. For Anthropic, the OAuth token is read from your macOS keychain (or `~/.claude/.credentials.json`). For the rest, `ANTHROPIC_AUTH_TOKEN` from the env.
+3. **Provider HTTP query** — picked from `ANTHROPIC_BASE_URL`. For Anthropic, the OAuth token is read by platform: macOS keychain → Windows Credential Manager → `~/.claude/.credentials.json`. For the rest, `ANTHROPIC_AUTH_TOKEN` from the env.
 
 ## Supported providers
 
@@ -111,6 +117,12 @@ cc-usage-bar install --format=bar-time \
 {"mode":"tint","text":"Ciallo～(∠・ω< )⌒★"}
 ```
 
+For stronger contrast, add `style:"reverse"` so the completed prefix is rendered as a reversed-color block:
+
+```json
+{"mode":"tint","text":"Ciallo～(∠・ω< )⌒★","style":"reverse"}
+```
+
 `cells` replaces the default block characters:
 
 ```json
@@ -172,7 +184,7 @@ base url:      <not set, defaults to anthropic>
 
 ## Privacy & API stability
 
-This tool calls **two undocumented Anthropic endpoints**: `/api/oauth/usage` (subscription quota) and reads OAuth tokens from the local macOS keychain. The `cc-switch` project (Tauri/Rust) has used the same approach in production for months. **Both endpoints may change without notice** — open an issue if you see a regression.
+This tool calls **one undocumented Anthropic endpoint**: `/api/oauth/usage` (subscription quota), and reads OAuth tokens from local OS-native credential stores (macOS keychain, Windows Credential Manager, or the JSON file). The `cc-switch` project (Tauri/Rust) has used the same approach in production for months. **The endpoint may change without notice** — open an issue if you see a regression.
 
 Tokens are read **only on your machine**. Nothing is uploaded anywhere. The tool makes one HTTPS request per refresh interval to the provider you've configured (or zero, when `rate_limits` is in stdin).
 
@@ -180,7 +192,7 @@ For non-Anthropic providers, the same is true: the API key from `ANTHROPIC_AUTH_
 
 ## Why no `jq` / `curl` dependency?
 
-Other statusline tools (e.g. `ccusage`) shell out to `jq` and `curl`. This one is pure Node.js (built-in `fetch` from Node 18+, `child_process` for the macOS keychain only). One `npm install -g` and you're done — no system tooling required.
+Other statusline tools (e.g. `ccusage`) shell out to `jq` and `curl`. This one is pure Node.js (built-in `fetch` from Node 18+, `child_process` only for the macOS keychain or Windows Credential Manager call). One `npm install -g` and you're done — no system tooling required, works on macOS / Linux / Windows.
 
 ## Acknowledgements
 

package/README.zh-CN.md

@@ -1,5 +1,11 @@
 # 中文说明
 
+[![npm version](https://img.shields.io/npm/v/cc-usage-bar.svg)](https://www.npmjs.com/package/cc-usage-bar)
+[![npm downloads](https://img.shields.io/npm/dm/cc-usage-bar.svg)](https://www.npmjs.com/package/cc-usage-bar)
+[![license](https://img.shields.io/npm/l/cc-usage-bar.svg)](LICENSE)
+[![node](https://img.shields.io/node/v/cc-usage-bar.svg)](package.json)
+[![GitHub](https://img.shields.io/badge/GitHub-TuYv%2Fcc--usage--bar-181717?logo=github)](https://github.com/TuYv/cc-usage-bar)
+
 [English](README.md)
 
 `cc-usage-bar` 可以把 Claude Code 的订阅用量显示在底部 statusline。它支持官方 Anthropic 订阅，也支持 Kimi、GLM/Zhipu、MiniMax、DeepSeek、StepFun、SiliconFlow、OpenRouter、Novita 等替代 provider。
@@ -45,7 +51,7 @@ Claude Code 的 statusline 本质上是一条 shell 命令，命令的 stdout
 
 1. **stdin `rate_limits`**：Claude Code 会把订阅用户的 `rate_limits` 传给 statusline，无需鉴权、无需网络。
 2. **本地缓存**：`/tmp/cc-oauth-usage.json`，成功缓存 30 秒，鉴权失败缓存 60 秒。
-3. **Provider HTTP 查询**：根据 `ANTHROPIC_BASE_URL` 自动选择 provider。Anthropic 会读取 macOS keychain 或 `~/.claude/.credentials.json`；其他 provider 使用环境变量 `ANTHROPIC_AUTH_TOKEN`。
+3. **Provider HTTP 查询**：根据 `ANTHROPIC_BASE_URL` 自动选择 provider。Anthropic 按平台读取凭证：macOS 钥匙串 → Windows Credential Manager → `~/.claude/.credentials.json`；其他 provider 使用环境变量 `ANTHROPIC_AUTH_TOKEN`。
 
 ## 支持的 Provider
 
@@ -116,6 +122,12 @@ cc-usage-bar install --format=bar-time \
 {"mode":"tint","text":"Ciallo～(∠・ω< )⌒★"}
 ```
 
+如果想让完成部分更像“填充底块”，可以加 `style:"reverse"`，完成部分会用反色块增强对比：
+
+```json
+{"mode":"tint","text":"Ciallo～(∠・ω< )⌒★","style":"reverse"}
+```
+
 #### cells：替换默认块字符
 
 ```json
@@ -179,7 +191,7 @@ base url:      <not set, defaults to anthropic>
 
 ## 隐私与 API 稳定性
 
-Anthropic 订阅用量依赖未公开接口 `/api/oauth/usage`，并会从本机 macOS keychain 或 `~/.claude/.credentials.json` 读取 Claude Code OAuth token。这些接口可能变化。
+Anthropic 订阅用量依赖未公开接口 `/api/oauth/usage`，并按平台读取本机 OAuth token：macOS 钥匙串、Windows Credential Manager、或 `~/.claude/.credentials.json`。这些接口可能变化。
 
 Token 只在你的机器上读取，不会上传到本项目的任何服务。工具只会请求你配置的 provider。使用 stdin `rate_limits` 时不需要网络。
 
@@ -187,7 +199,7 @@ Token 只在你的机器上读取，不会上传到本项目的任何服务。
 
 ## 为什么不依赖 jq / curl
 
-这个工具是纯 Node.js 实现，Node 18+ 自带 `fetch`，只在 macOS 读取 keychain 时使用 `child_process`。安装后直接可用，不需要额外安装 `jq` 或 `curl`。
+这个工具是纯 Node.js 实现，Node 18+ 自带 `fetch`，只在读取 macOS 钥匙串或 Windows Credential Manager 时使用 `child_process`。安装后直接可用，不需要额外安装 `jq` 或 `curl`，跨 macOS / Linux / Windows。
 
 ## 致谢
 

package/bin/cc-usage-bar-wrap.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+require('../dist/src/wrap.js')
+  .main()
+  .catch(() => {
+    // silent — never pollute the statusline
+    process.exit(0);
+  });

package/dist/src/cli.js

@@ -49,25 +49,6 @@ function readPkgVersion() {
         return '0.0.0';
     }
 }
-function formatCountdown(iso) {
-    if (!iso)
-        return 'unknown';
-    const target = new Date(iso).getTime();
-    if (Number.isNaN(target))
-        return 'unknown';
-    const diffMs = target - Date.now();
-    if (diffMs <= 0)
-        return 'now';
-    const totalMin = Math.floor(diffMs / 60_000);
-    const days = Math.floor(totalMin / (60 * 24));
-    const hours = Math.floor((totalMin % (60 * 24)) / 60);
-    const mins = totalMin % 60;
-    if (days > 0)
-        return `${days}d ${hours}h ${mins}m`;
-    if (hours > 0)
-        return `${hours}h ${mins}m`;
-    return `${mins}m`;
-}
 function loadSettingsOrExit() {
     try {
         return (0, settings_1.readSettings)();
@@ -169,9 +150,9 @@ async function runStatus() {
         if (result.data.planName)
             console.log(`plan:          ${result.data.planName}`);
         if (fh)
-            console.log(`5-hour:        ${Math.round(fh.utilization)}% (resets in ${formatCountdown(fh.resets_at)})`);
+            console.log(`5-hour:        ${Math.round(fh.utilization)}% (resets in ${(0, format_1.formatCountdown)(fh.resets_at)})`);
         if (wk)
-            console.log(`7-day:         ${Math.round(wk.utilization)}% (resets in ${formatCountdown(wk.resets_at)})`);
+            console.log(`7-day:         ${Math.round(wk.utilization)}% (resets in ${(0, format_1.formatCountdown)(wk.resets_at)})`);
     }
     else {
         const d = result.data;
@@ -193,12 +174,12 @@ program
     .command('install')
     .description('Install statusline integration into ~/.claude/settings.json')
     .option('-f, --force', 'overwrite if already installed')
-    .option('--format <preset>', `render preset (${format_1.FORMAT_PRESETS.join(' | ')})`, 'compact')
+    .option('--format <preset>', `render preset (${format_1.FORMAT_PRESETS.join(' | ')})`, 'bar-countdown')
     .option('--bar-width <n>', 'bar width when format includes a bar (1-50)', '10')
     .option('--bar-spec <json>', 'custom bar JSON spec (cells, tint, or frames)')
     .action(async (opts) => {
     const installOpts = {};
-    if (opts.format && opts.format !== 'compact') {
+    if (opts.format && opts.format !== 'bar-countdown') {
         if (!(0, format_1.isValidPreset)(opts.format)) {
             console.error(`error: --format must be one of ${format_1.FORMAT_PRESETS.join(', ')}`);
             process.exit(1);
@@ -235,6 +216,25 @@ program
     .action(async () => {
     await runStatus();
 });
+program
+    .command('agents')
+    .description('Print the AI-readable install guide (for piping into Claude Code, Cursor, etc.)')
+    .action(() => {
+    const candidates = [
+        path.join(__dirname, '..', '..', 'AGENTS.md'),
+        path.join(__dirname, '..', 'AGENTS.md'),
+    ];
+    for (const p of candidates) {
+        try {
+            process.stdout.write(fs.readFileSync(p, 'utf8'));
+            return;
+        }
+        catch {
+        }
+    }
+    console.error('AGENTS.md not found in package.');
+    process.exit(1);
+});
 program.parseAsync(process.argv).catch((e) => {
     console.error(e instanceof Error ? e.message : String(e));
     process.exit(1);

package/dist/src/fetch.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.readStdinJson = readStdinJson;
 exports.extractFromStdin = extractFromStdin;
 exports.run = run;
+exports.parseArg = parseArg;
 exports.main = main;
 const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
@@ -46,6 +47,7 @@ const format_1 = require("./format");
 const CACHE_PATH = path.join(os.tmpdir(), 'cc-oauth-usage.json');
 const SUCCESS_TTL_MS = 30_000;
 const AUTH_FAIL_TTL_MS = 60_000;
+const TRANSIENT_FAIL_TTL_MS = 60_000;
 const STDIN_TIMEOUT_MS = 500;
 async function readStdinJson(timeoutMs = STDIN_TIMEOUT_MS) {
     if (process.stdin.isTTY)
@@ -147,15 +149,19 @@ function writeCache(entry) {
 }
 function isCacheFresh(entry) {
     const age = Date.now() - entry.fetched_at;
+    if (age < 0)
+        return false;
     if (entry.status === 'ok')
-        return age >= 0 && age < SUCCESS_TTL_MS;
+        return age < SUCCESS_TTL_MS;
     if (entry.status === 'auth_failed')
-        return age >= 0 && age < AUTH_FAIL_TTL_MS;
+        return age < AUTH_FAIL_TTL_MS;
+    if (entry.status === 'rate_limited')
+        return age < TRANSIENT_FAIL_TTL_MS;
     return false;
 }
 async function run(opts = {}) {
     if (!opts.skipStdin) {
-        const stdinJson = await readStdinJson();
+        const stdinJson = opts.stdinJson !== undefined ? opts.stdinJson : await readStdinJson();
         const fromStdin = stdinAsSubscription(extractFromStdin(stdinJson));
         if (fromStdin) {
             return {
@@ -181,12 +187,18 @@ async function run(opts = {}) {
     }
     const cache = opts.forceFresh ? null : readCache();
     if (cache && cache.adapter_id === adapter.id && isCacheFresh(cache)) {
+        let cacheStatusReport = 'hit';
+        if (cache.status === 'auth_failed')
+            cacheStatusReport = 'auth_failed_cached';
+        else if (cache.status === 'rate_limited')
+            cacheStatusReport = 'rate_limited_cached';
         return {
             data: cache.data,
             source: 'cache',
             adapterId: adapter.id,
-            cacheStatus: cache.status === 'auth_failed' ? 'auth_failed_cached' : 'hit',
+            cacheStatus: cacheStatusReport,
             authFailed: cache.status === 'auth_failed',
+            error: cache.error,
         };
     }
     const cacheStatusOnMiss = cache && cache.adapter_id !== adapter.id ? 'adapter_changed' : cache ? 'expired' : 'miss';
@@ -202,7 +214,13 @@ async function run(opts = {}) {
         };
     }
     if (result.authFailed) {
-        writeCache({ fetched_at: Date.now(), status: 'auth_failed', adapter_id: adapter.id, data: null });
+        writeCache({
+            fetched_at: Date.now(),
+            status: 'auth_failed',
+            adapter_id: adapter.id,
+            data: null,
+            error: result.error,
+        });
         return {
             data: null,
             source: 'api',
@@ -212,6 +230,17 @@ async function run(opts = {}) {
             error: result.error,
         };
     }
+    const httpStatus = result.status ?? 0;
+    const isTransientHttp = httpStatus === 429 || (httpStatus >= 500 && httpStatus < 600);
+    if (isTransientHttp) {
+        writeCache({
+            fetched_at: Date.now(),
+            status: 'rate_limited',
+            adapter_id: adapter.id,
+            data: null,
+            error: result.error,
+        });
+    }
     return {
         data: null,
         source: 'api',
@@ -221,6 +250,17 @@ async function run(opts = {}) {
         error: result.error,
     };
 }
+function logEvent(event) {
+    const target = process.env.CC_USAGE_LOG;
+    if (!target)
+        return;
+    try {
+        const line = JSON.stringify({ ts: new Date().toISOString(), pid: process.pid, ...event }) + '\n';
+        fs.appendFileSync(target, line);
+    }
+    catch {
+    }
+}
 function parseArg(args, name) {
     const eq = args.find((a) => a.startsWith(`--${name}=`));
     if (eq)
@@ -250,14 +290,27 @@ Custom template (env, overrides --format):
   CC_USAGE_BAR_SPEC     Same JSON shape as --bar-spec
 
 Presets render like:
-  compact    5h 47% Wk 59%
-  numeric    47% / 59%
-  time       47% until 18:23 / 59% until 5/12 09:00
-  bar        [█████░░░░░] 47% / [██████░░░░] 59%
-  bar-time   [█████░░░░░] 47% until 18:23 / [██████░░░░] 59% until 5/12 09:00
+  compact         5h 47% Wk 59%
+  numeric         47% / 59%
+  time            47% until 18:23 / 59% until 5/12 09:00
+  countdown       47% in 1h23m / 59% in 2d6h
+  bar             [█████░░░░░] 47% / [██████░░░░] 59%
+  bar-time        [█████░░░░░] 47% until 18:23 / [██████░░░░] 59% until 5/12 09:00
+  bar-countdown   [█████░░░░░] 47% in 1h23m / [██████░░░░] 59% in 2d6h
+
+Per-tier color ramps (override defaults — comma-separated "<min>:<color>"):
+  CC_USAGE_COLORS_5H        e.g. '0:green,60:yellow,85:#ff3333'
+  CC_USAGE_COLORS_WK        e.g. '0:#888,60:#ffaa00,85:boldRed'
+  CC_USAGE_COLORS_BALANCE   used by balance providers (DeepSeek/OpenRouter/...)
+  Color tokens:
+    - named:  green/yellow/red/blue/magenta/cyan/white/gray/dim,
+              boldGreen/boldYellow/boldRed/boldBlue/boldMagenta/boldCyan/boldWhite
+    - hex:    '#RRGGBB' or '#RGB' (24-bit truecolor; needs a truecolor terminal)
+    - 'none': skip color in that band
 
 Other:
   NO_COLOR=1            Force-disable colors
+  CC_USAGE_LOG=<path>   Append one JSON line per invocation (source / cacheStatus / error) for diagnosing call frequency
   --help                Show this message
 `;
 async function main() {
@@ -287,7 +340,24 @@ async function main() {
     const barSpec = (0, format_1.parseBarSpec)(barSpecArg ?? barSpecEnv);
     if (barSpec)
         fmt.barSpec = barSpec;
+    const RAMP_ENV = [
+        ['colorRamp5h', 'CC_USAGE_COLORS_5H'],
+        ['colorRampWk', 'CC_USAGE_COLORS_WK'],
+        ['colorRampBalance', 'CC_USAGE_COLORS_BALANCE'],
+    ];
+    for (const [key, envName] of RAMP_ENV) {
+        const ramp = (0, format_1.parseColorRamp)(process.env[envName]);
+        if (ramp)
+            fmt[key] = ramp;
+    }
     const result = await run({ skipStdin });
+    logEvent({
+        source: result.source,
+        cacheStatus: result.cacheStatus,
+        adapterId: result.adapterId,
+        authFailed: result.authFailed,
+        error: result.error ?? null,
+    });
     if (wantJson) {
         process.stdout.write(JSON.stringify({
             data: result.data,