glm-quota-line 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.8.0
+
+- Added progressive refresh backoff: new sessions start at 3-minute intervals, advance to 5 minutes after 5 refreshes, and cap at 10 minutes after 5 more — giving new users fast feedback while reducing API pressure in long sessions
+- Added low-quota override: when remaining quota drops below 30%, the refresh interval is forced back to 3 minutes regardless of current tier, so users see accurate data when it matters most
+- Low-quota refreshes do not advance the tier counter, preserving the previous tier when quota recovers
+- SessionStart (startup / resume / clear) resets the tier to level 0, ensuring fresh sessions always start responsive
+- Rate-limited and failed responses no longer advance the tier counter
+- Old cache files without tier fields automatically migrate to tier 0
+- Simplified README quick start to two commands with style config clearly marked as optional
+
+## 0.7.0
+
+- Added `--version` and `version` so the installed CLI version is visible directly from the command line
+- Added `check-update` to compare the installed version with npm and print a suggested upgrade command without auto-updating
+- Improved CLI help and README docs with upgrade and version-check examples
+- Corrected published package metadata to include `README.en.md` in the npm file list
+
 ## 0.6.0
 
 - Added official international GLM quota endpoint support for `api.z.ai` while preserving domestic `open.bigmodel.cn` detection

package/README.en.md

@@ -0,0 +1,122 @@
+<h1 align="center">glm-quota-line</h1>
+
+<p align="center">
+  One-command install, zero dependencies. Shows accurate Zhipu GLM Coding Plan quota balance and reset time in the Claude Code status line — data from the official API, not estimated.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/glm-quota-line"><img alt="npm version" src="https://img.shields.io/npm/v/glm-quota-line?logo=npm&color=cb3837"></a>
+  <a href="https://www.npmjs.com/package/glm-quota-line"><img alt="node version" src="https://img.shields.io/node/v/glm-quota-line?logo=node.js&color=339933"></a>
+  <a href="./LICENSE"><img alt="license" src="https://img.shields.io/npm/l/glm-quota-line"></a>
+  <img alt="dependencies" src="https://img.shields.io/badge/dependencies-0-2ea44f">
+</p>
+
+<p align="center">
+  <a href="./README.md">简体中文</a>
+</p>
+
+`glm-quota-line` reads the Zhipu GLM Coding Plan quota API, caches results, and prints a short status line for Claude Code's `statusLine.command`. A `SessionStart` hook pre-refreshes the cache so new sessions never show stale data.
+
+## Features
+
+- **One-command install** — `glm-quota-line install` wires status line and `SessionStart` hooks into Claude Code automatically
+- **Accurate quota display** — reads directly from the official GLM quota API, not estimated; shows both 5-hour and weekly token quotas
+- **Domestic + international endpoints** — auto-detects `open.bigmodel.cn` and `api.z.ai`
+- **Zero dependencies** — no runtime deps, single-purpose CLI
+- **Smart caching** — refreshes by session, TTL, and token usage; supports manual auth overrides for proxy/gateway setups
+
+## Quick Start
+
+```bash
+npm install -g glm-quota-line
+glm-quota-line install
+```
+
+That's it — works out of the box. Default output (`style=text`, `theme=ansi`, `palette=dark`):
+
+```text
+GLM Lite | 5h 91% | week 47% | reset 14:47
+```
+
+Both the 5-hour quota (primary) and weekly quota (secondary) are shown with automatic reset time.
+
+Upgrade:
+
+```bash
+npm install -g glm-quota-line
+glm-quota-line check-update
+```
+
+## Custom Styles
+
+All style options are optional — adjust only if needed:
+
+```bash
+glm-quota-line config set style bar       # layout: text / compact / bar
+glm-quota-line config set theme ansi      # color: plain / ansi
+glm-quota-line config set palette dark    # palette: dark / mono (only when theme=ansi)
+```
+
+Different `style` outputs:
+
+```text
+# style=text (default)
+GLM Lite | 5h 91% | week 47% | reset 14:47
+
+# style=compact
+GLM 5h 91% W 47% | 14:47
+
+# style=bar
+GLM Lite █░░░░░░░░░ 91% | W 47% | 14:47
+```
+
+Recommended combinations:
+
+| Use case       | Config                                        |
+| -------------- | --------------------------------------------- |
+| Dark terminal  | `style=bar`, `theme=ansi`, `palette=dark`     |
+| Light terminal | `style=compact`, `theme=ansi`, `palette=mono` |
+| Plain fallback | any `style`, `theme=plain`                    |
+
+## Custom Auth
+
+If Claude Code runs behind a gateway or proxy and the injected `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_BASE_URL` are not the real values:
+
+```bash
+glm-quota-line config set auth-token <your-real-token>
+glm-quota-line config set base-url https://open.bigmodel.cn/api/anthropic
+# or
+glm-quota-line config set base-url https://api.z.ai/api/anthropic
+```
+
+Clear with `glm-quota-line config unset auth-token` / `base-url`. Stored overrides take precedence over Claude-injected environment variables.
+
+## Commands
+
+```bash
+glm-quota-line [--style text|compact|bar] [--display left|used|both]
+               [--theme plain|ansi] [--palette dark|mono]
+
+glm-quota-line install [--force]
+glm-quota-line uninstall
+glm-quota-line version
+glm-quota-line check-update
+glm-quota-line config show
+glm-quota-line config set <style|display|theme|palette|auth-token|base-url> <value>
+glm-quota-line config unset <key>
+```
+
+Run `glm-quota-line --help` for full descriptions.
+
+Use `glm-quota-line --version` to print the installed version. `check-update` only checks and prints the suggested upgrade command; it does not modify your environment.
+
+## Notes
+
+- Only `TOKENS_LIMIT` quotas are shown; `TIME_LIMIT` / MCP usage is ignored
+- Missing auth returns `GLM | auth expired`; API failures return `GLM | quota unavailable`
+- `install` does not replace an unmanaged status line unless `--force` is used
+- `install --force` backs up the previous entry; `uninstall` restores it when possible
+
+## License
+
+[MIT](./LICENSE)

package/README.md

@@ -1,7 +1,7 @@
 <h1 align="center">glm-quota-line</h1>
 
 <p align="center">
-  Zero-dependency CLI for showing GLM Coding Plan quota in the Claude Code status line.
+  一行命令安装、零依赖，在 Claude Code 状态栏实时显示智谱（Zhipu）GLM Coding Plan 配额余额与重置时间。数据来自官方接口，精准非估算。
 </p>
 
 <p align="center">
@@ -12,127 +12,86 @@
 </p>
 
 <p align="center">
-  <a href="./README.zh-CN.md">简体中文</a>
+  <a href="./README.en.md">English</a>
 </p>
 
-## Overview
+`glm-quota-line` 读取智谱（Zhipu）GLM Coding Plan 配额接口、缓存结果，并输出一行适合 Claude Code `statusLine.command` 的状态文本。通过 `SessionStart` hook 预刷新缓存，新会话不会显示旧配额。
 
-`glm-quota-line` reads the GLM quota endpoint, caches successful responses, and prints a single short line for `statusLine.command`.
+## 功能
 
-It also installs a Claude Code `SessionStart` hook to pre-refresh the quota cache before a new session renders the status line.
+- **一行命令安装** — `glm-quota-line install` 自动接入 Claude Code 状态栏和 `SessionStart` hook
+- **精准配额显示** — 数据来自官方配额接口，非估算；同时展示 5 小时和周 token 配额
+- **国内 + 国际端点** — 自动识别 `open.bigmodel.cn` 和 `api.z.ai`
+- **零依赖** — 无运行时依赖，单一用途
+- **智能缓存** — 按会话、TTL 和 token 用量刷新；支持代理/网关手动覆盖鉴权
 
-It is intentionally scoped to one host only: Claude Code.
-
-## Why
-
-- Built for a single purpose: show GLM quota clearly in Claude Code
-- Small and predictable: no runtime dependencies, no unnecessary abstraction
-- Practical for real usage: cache-aware, session-aware, and easy to install
-
-## Features
-
-- Built for Claude Code `statusLine.command`
-- No runtime dependencies
-- Optional `text`, `compact`, and `bar` layouts
-- Optional ANSI color themes for dark and light terminals
-- Manual `auth-token` and `base-url` overrides for proxy or gateway setups
-- Automatic install and uninstall for Claude Code status line integration
-- SessionStart pre-refresh so a new Claude session does not briefly show stale quota
-
-## Installation
-
-Recommended:
+## 快速开始
 
 ```bash
 npm install -g glm-quota-line
+glm-quota-line install
 ```
 
-From a local clone:
+两步完成，开箱即用。默认输出（`style=text`，`theme=ansi`，`palette=dark`）：
 
-```bash
-npm install -g .
+```text
+GLM Lite | 5h 91% | week 47% | reset 14:47
 ```
 
-`npx` is fine for one-off previews, but global install is the better default for Claude Code integration because `install` writes stable executable paths into both `statusLine.command` and the managed `SessionStart` hooks.
+同时显示 5 小时配额（主要）和周配额（次要），并自动展示重置时间。
 
-## Quick Start
+升级版本：
 
 ```bash
-glm-quota-line install
-glm-quota-line config set style bar
-glm-quota-line config set theme ansi
-glm-quota-line config set palette dark
+npm install -g glm-quota-line
+glm-quota-line check-update
 ```
 
-For a one-off preview:
+## 自定义样式
+
+所有样式配置均为可选，按需调整：
 
 ```bash
-glm-quota-line --style compact
+glm-quota-line config set style bar       # 布局: text / compact / bar
+glm-quota-line config set theme ansi      # 配色: plain / ansi
+glm-quota-line config set palette dark    # 色板: dark / mono（仅 theme=ansi 时生效）
 ```
 
-## Output
+不同 style 效果：
 
 ```text
-GLM Lite | 5h left 91% | week 47% | reset 14:47
+# style=text（默认）
+GLM Lite | 5h 91% | week 47% | reset 14:47
 
+# style=compact
 GLM 5h 91% W 47% | 14:47
 
+# style=bar
 GLM Lite █░░░░░░░░░ 91% | W 47% | 14:47
 ```
 
-## Recommended Setups
-
-| Use case       | Config                                        |
-| -------------- | --------------------------------------------- |
-| Dark terminal  | `style=bar`, `theme=ansi`, `palette=dark`     |
-| Light terminal | `style=compact`, `theme=ansi`, `palette=mono` |
-| Plain fallback | any `style`, `theme=plain`                    |
-
-## Color Presets
+推荐搭配：
 
-`style` controls layout. `theme` enables or disables ANSI color. `palette` only applies when `theme=ansi`.
+| 使用场景   | 配置                                          |
+| ---------- | --------------------------------------------- |
+| 深色终端   | `style=bar`, `theme=ansi`, `palette=dark`     |
+| 浅色终端   | `style=compact`, `theme=ansi`, `palette=mono` |
+| 纯文本回退 | 任意 `style`，`theme=plain`                   |
 
-- Dark terminal: `theme=ansi` + `palette=dark`
-- Light terminal: `theme=ansi` + `palette=mono`
-- Maximum compatibility: `theme=plain`
+## 自定义鉴权
 
-Examples:
-
-```bash
-glm-quota-line config set style text
-glm-quota-line config set theme ansi
-glm-quota-line config set palette dark
-
-glm-quota-line config set style compact
-glm-quota-line config set theme ansi
-glm-quota-line config set palette mono
-
-glm-quota-line config set theme plain
-```
-
-Set `NO_COLOR=1` to force plain output.
-
-## Manual Credential Overrides
-
-If Claude Code is running behind a gateway or proxy and the injected `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_BASE_URL` are not the real values, store explicit overrides:
+如果 Claude Code 运行在代理或网关后面，注入的 `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_BASE_URL` 不是实际值：
 
 ```bash
 glm-quota-line config set auth-token <your-real-token>
 glm-quota-line config set base-url https://open.bigmodel.cn/api/anthropic
-# or
+# 或
 glm-quota-line config set base-url https://api.z.ai/api/anthropic
 ```
 
-Clear them later with:
-
-```bash
-glm-quota-line config unset auth-token
-glm-quota-line config unset base-url
-```
-
-Stored overrides take precedence over Claude-injected environment variables. `config show` redacts the token, but the local config file still stores the real value in plain text.
+清除：`glm-quota-line config unset auth-token` / `base-url`。手动保存的值优先于 Claude 注入的环境变量。
 
-## Commands
+## 命令
 
 ```bash
 glm-quota-line [--style text|compact|bar] [--display left|used|both]
@@ -140,28 +99,24 @@ glm-quota-line [--style text|compact|bar] [--display left|used|both]
 
 glm-quota-line install [--force]
 glm-quota-line uninstall
+glm-quota-line version
+glm-quota-line check-update
 glm-quota-line config show
-glm-quota-line config set style <text|compact|bar>
-glm-quota-line config set display <left|used|both>
-glm-quota-line config set theme <plain|ansi>
-glm-quota-line config set palette <dark|mono>
-glm-quota-line config set auth-token <token>
-glm-quota-line config set base-url <url>
-glm-quota-line config unset <style|display|theme|palette|auth-token|base-url>
+glm-quota-line config set <style|display|theme|palette|auth-token|base-url> <value>
+glm-quota-line config unset <key>
 ```
 
-Run `glm-quota-line --help` for the full command descriptions and examples.
+完整说明运行 `glm-quota-line --help`。
+
+`glm-quota-line --version` 可直接查看当前安装版本；`check-update` 只检查并提示升级命令，不会自动修改环境。
 
-## Notes
+## 说明
 
-- Default output is plain text
-- Missing or expired auth returns `GLM | auth expired`
-- API or parsing failures return `GLM | quota unavailable`
-- Only `TOKENS_LIMIT` quotas are shown; `TIME_LIMIT` / MCP usage is ignored
-- `install` wires both the status line command and managed `SessionStart` hooks
-- `install` does not replace an unmanaged Claude status line unless `--force` is used
-- `install --force` backs up the previous entry and `uninstall` restores it when possible
+- 只展示 `TOKENS_LIMIT` 配额，忽略 `TIME_LIMIT` / MCP 使用量
+- 鉴权缺失返回 `GLM | auth expired`；接口异常返回 `GLM | quota unavailable`
+- `install` 默认不会覆盖非本工具管理的状态栏，除非使用 `--force`
+- `install --force` 会备份旧配置，`uninstall` 会在可能时恢复
 
-## License
+## 许可证
 
 [MIT](./LICENSE)

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "glm-quota-line",
-  "version": "0.6.0",
-  "description": "Claude Code status line helper for GLM Coding Plan quota.",
+  "version": "0.8.0",
+  "description": "Zhipu GLM Coding Plan quota monitor for Claude Code status line.",
   "type": "module",
   "license": "MIT",
   "author": "caojian",
   "preferGlobal": true,
   "keywords": [
     "claude-code",
-    "statusline",
     "glm",
+    "zhipu",
+    "z.ai",
+    "coding-plan",
     "quota",
-    "cli"
+    "statusline"
   ],
   "repository": {
     "type": "git",
@@ -27,7 +29,7 @@
   "files": [
     "src",
     "README.md",
-    "README.zh-CN.md",
+    "README.en.md",
     "LICENSE",
     "CHANGELOG.md"
   ],

package/src/claude/install.js

@@ -32,7 +32,7 @@ function isToolManagedStatusLine(statusLine) {
   return isToolManagedCommand(statusLine?.command);
 }
 
-export function getStatusLineEntryPath() {
+function getStatusLineEntryPath() {
   return path.resolve(__dirname, "..", "cli", "index.js");
 }
 
@@ -53,38 +53,41 @@ function isToolManagedHook(hook) {
   return hook?.type === "command" && isToolManagedCommand(hook.command);
 }
 
-function removeManagedSessionStartHooks(settings) {
-  if (!settings.hooks || typeof settings.hooks !== "object") {
-    return false;
-  }
-
-  const existingGroups = Array.isArray(settings.hooks.SessionStart) ? settings.hooks.SessionStart : null;
-  if (!existingGroups) {
-    return false;
-  }
+function filterManagedHooksFromGroups(groups) {
+  let hadManaged = false;
+  const filtered = [];
 
-  let removed = false;
-  const nextGroups = [];
-
-  for (const group of existingGroups) {
+  for (const group of groups) {
     if (!group || typeof group !== "object" || !Array.isArray(group.hooks)) {
-      nextGroups.push(group);
+      filtered.push(group);
       continue;
     }
 
     const nextHooks = group.hooks.filter((hook) => !isToolManagedHook(hook));
     if (nextHooks.length !== group.hooks.length) {
-      removed = true;
+      hadManaged = true;
     }
 
     if (nextHooks.length > 0) {
-      nextGroups.push({
-        ...group,
-        hooks: nextHooks
-      });
+      filtered.push({ ...group, hooks: nextHooks });
     }
   }
 
+  return { groups: filtered, hadManaged };
+}
+
+function removeManagedSessionStartHooks(settings) {
+  if (!settings.hooks || typeof settings.hooks !== "object") {
+    return false;
+  }
+
+  const existingGroups = Array.isArray(settings.hooks.SessionStart) ? settings.hooks.SessionStart : null;
+  if (!existingGroups) {
+    return false;
+  }
+
+  const { groups: nextGroups, hadManaged: removed } = filterManagedHooksFromGroups(existingGroups);
+
   if (nextGroups.length > 0) {
     settings.hooks.SessionStart = nextGroups;
   } else {
@@ -101,21 +104,10 @@ function removeManagedSessionStartHooks(settings) {
 function installManagedSessionStartHooks(settings, command) {
   const existingGroups =
     settings.hooks && typeof settings.hooks === "object" && Array.isArray(settings.hooks.SessionStart)
-      ? settings.hooks.SessionStart.map((group) =>
-          group && typeof group === "object" ? { ...group, hooks: Array.isArray(group.hooks) ? [...group.hooks] : group.hooks } : group
-        )
+      ? settings.hooks.SessionStart
       : [];
 
-  const nextGroups = existingGroups.map((group) => {
-    if (!group || typeof group !== "object" || !Array.isArray(group.hooks)) {
-      return group;
-    }
-
-    return {
-      ...group,
-      hooks: group.hooks.filter((hook) => !isToolManagedHook(hook))
-    };
-  });
+  const { groups: nextGroups } = filterManagedHooksFromGroups(existingGroups);
 
   for (const matcher of SESSION_START_MATCHERS) {
     const targetGroup = nextGroups.find(
@@ -123,21 +115,13 @@ function installManagedSessionStartHooks(settings, command) {
     );
 
     if (targetGroup) {
-      targetGroup.hooks.push({
-        type: "command",
-        command
-      });
+      targetGroup.hooks.push({ type: "command", command });
       continue;
     }
 
     nextGroups.push({
       matcher,
-      hooks: [
-        {
-          type: "command",
-          command
-        }
-      ]
+      hooks: [{ type: "command", command }]
     });
   }
 

package/src/claude/sessionStart.js

@@ -3,7 +3,7 @@ import { resolveQuotaStatus } from "../core/quota/service.js";
 import { readStatusLineInput } from "./input.js";
 import { readToolConfig } from "./settings.js";
 
-export const SESSION_START_MATCHERS = ["startup", "resume", "clear", "compact"];
+export const SESSION_START_MATCHERS = ["startup", "resume", "clear"];
 
 export async function refreshQuotaOnSessionStart(options = {}) {
   const hookInput = await readStatusLineInput(options.stdin ?? process.stdin);
@@ -12,10 +12,7 @@ export async function refreshQuotaOnSessionStart(options = {}) {
   const resolveQuotaStatusFn = options.resolveQuotaStatusFn ?? resolveQuotaStatus;
   const config = {
     ...loadConfigFn(options.env ?? process.env, userConfig),
-    sessionId: hookInput?.session_id || "",
-    // SessionStart runs before statusLine has token totals, so treat a new session
-    // as starting from zero to preserve later token-threshold refreshes.
-    observedTokens: 0
+    sessionId: hookInput?.session_id || ""
   };
 
   return resolveQuotaStatusFn(config, {

package/src/claude/settings.js

@@ -10,8 +10,9 @@ import {
   isValidTheme
 } from "../shared/constants.js";
 import { readJsonFile, writeJsonFile } from "../shared/jsonFile.js";
+import { normalizeOptionalString } from "../shared/config.js";
 
-export function getClaudeDir() {
+function getClaudeDir() {
   return path.join(os.homedir(), ".claude");
 }
 
@@ -23,15 +24,6 @@ export function getToolConfigPath() {
   return path.join(getClaudeDir(), "glm-quota-line.json");
 }
 
-function normalizeOptionalString(value) {
-  if (typeof value !== "string") {
-    return undefined;
-  }
-
-  const trimmed = value.trim();
-  return trimmed || undefined;
-}
-
 function redactSecret(value) {
   if (!value) {
     return value;

package/src/cli/args.js

@@ -26,6 +26,11 @@ export function parseArgs(argv = process.argv.slice(2)) {
       continue;
     }
 
+    if (arg === "--version" || arg === "-v") {
+      options.version = true;
+      continue;
+    }
+
     if (arg === "--force") {
       options.force = true;
       continue;
@@ -67,4 +72,3 @@ export function parseArgs(argv = process.argv.slice(2)) {
   options.positionals = positionals;
   return options;
 }
-

package/src/cli/commands.js

@@ -13,6 +13,8 @@ import {
 } from "../claude/settings.js";
 import { installClaudeStatusLine, uninstallClaudeStatusLine } from "../claude/install.js";
 import { refreshQuotaOnSessionStart } from "../claude/sessionStart.js";
+import { checkForUpdates } from "./update.js";
+import { getPackageVersion } from "../shared/packageInfo.js";
 
 function isNonEmptyString(value) {
   return typeof value === "string" && value.trim().length > 0;
@@ -66,9 +68,36 @@ const CONFIG_KEYS = {
   }
 };
 
-export async function handleCommand(args, output = process.stdout) {
+export async function handleCommand(args, output = process.stdout, dependencies = {}) {
+  const getVersion = dependencies.getVersion || getPackageVersion;
+  const runUpdateCheck = dependencies.runUpdateCheck || checkForUpdates;
   const [command, subcommand, key, value] = args.positionals;
 
+  if (command === "version") {
+    output.write(`glm-quota-line ${await getVersion()}\n`);
+    return true;
+  }
+
+  if (command === "check-update") {
+    const result = await runUpdateCheck();
+    output.write(`glm-quota-line ${result.currentVersion}\n`);
+
+    if (result.status === "up-to-date") {
+      output.write(`latest: ${result.latestVersion}\nstatus: up to date\n`);
+      return true;
+    }
+
+    if (result.status === "update-available") {
+      output.write(
+        `latest: ${result.latestVersion}\nstatus: update available\nupgrade: ${result.upgradeCommand}\n`
+      );
+      return true;
+    }
+
+    output.write(`status: unable to check updates\nreason: ${result.errorMessage}\n`);
+    return true;
+  }
+
   if (command === "install") {
     const result = await installClaudeStatusLine(undefined, undefined, undefined, {
       force: Boolean(args.force)