glm-quota-line 1.2.0 → 1.3.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.3.1
+
+- Fixed "quota unavailable" on api.z.ai / open.bigmodel.cn: the quota endpoint now returns `{"code":200,...}` without a top-level `success` flag, which made every response parse as unavailable (#6)
+- Added support for credit-based Coding Plans: their 5h/weekly windows are reported as `CREDIT_LIMIT` entries (`usage`/`currentValue`/`remaining`) instead of `TOKENS_LIMIT`, which previously produced no quotas (#6)
+
+## 1.3.0
+
+- Added `commands` subcommand: list every command with a machine-readable schema via `--json` (name / summary / sideEffect / args / examples), for AI agents and scripting
+- Added per-subcommand `--help` (e.g. `model --help`, `config set --help`) — focused help derived from a single command registry
+- **User-customizable model mapping table** — model context window sizes are now managed by the user at runtime. The bundled `data/models.json` is just a frozen base; your local `modelMap` overlays it, so adapting to a new model (e.g. `glm-5.2` with 1M context) needs only `model set <id> <size>` — no package update or upgrade required
+- Added `model` subcommands: `list`, `get`, `set`, `remove` — manage model context window size mappings via CLI
+- Added `modelMap` persistence in tool config — custom model sizes survive across sessions
+- Added `config reset [--models] [--yes]` — restore user config to defaults. `--models` limits the reset to custom model mappings. Preserves install state; prompts unless `--yes` (required in non-interactive sessions)
+- Model ids reported with a bracket suffix (e.g. `glm-5.2[1M]`) are now normalized to the bare id for lookup and display
+- Updated default table: added `glm-5.2` (1M context), removed `glm-5` and `glm-5.1` (no longer in plan)
+- Added `reset-format` config (`time` / `countdown`) — show reset time as countdown duration instead of time point
+- Weekly quota now displays reset time (time point or countdown) alongside the progress bar
+- Context window resolution now relies solely on the local model map: stdin `context_window_size` is ignored, and stdin-provided window percentages are no longer used as a fallback (they are often inaccurate). If the current model id is not in the map, the context segment is simply not shown rather than guessing
+- ctx cache now keyed by session id + model id: token usage can be 0 or missing on individual status-line frames (session start, between requests), which would make the context segment flash. The cache falls back to the last valid value for the same session and model so the display stays stable — a stale value from a different session or model is never shown
+- Refactored command dispatch into `configCommand.js` / `modelCommand.js`, and extracted a shared `bar.js` and a context-scoped `cache.js`. No behavior change
+- Hardcoded `glm-4.7` fallback remains as a defensive guard against `data/models.json` I/O failure
+
 ## 1.2.0
 
 - Added interactive TUI configuration: `glm-quota-line configure` — live preview, per-component toggle and style, global options

package/README.en.md

@@ -1,7 +1,8 @@
 <h1 align="center">glm-quota-line</h1>
 
 <p align="center">
-  A Zhipu GLM Coding Plan quota monitor built for Claude Code. Accurate, real-time data from the official site — no window switching, just glance and go.
+  A Zhipu GLM Coding Plan quota monitor built for Claude Code<br>
+  <strong>Focus on coding without switching windows to check your quota</strong>
 </p>
 
 <p align="center">
@@ -15,20 +16,25 @@
   <a href="./README.md">简体中文</a>
 </p>
 
-## Features
+## Core Value
 
-- **Terminal quick check** — run `glm-quota-line` in any terminal to view your quota (including MCP) without launching Claude Code
-- **Claude Code status line** — auto-embeds in the status bar after install, shows quota balance, reset time, and context window usage in real time
-- **Bar visualization** — default bar style shows remaining quota at a glance; weekly quota shows theoretical budget shadow
-- **Weekly pacing analysis** — calculates usage speed based on work days, auto-highlights when exceeding theoretical budget
-- **JSON output** — `--json` flag outputs structured data for scripting
-- **Interactive configuration** — `glm-quota-line configure` launches a TUI with live preview and per-component controls
-- **Component-level control** — each display component (plan, 5h, week, reset, context) can be individually toggled and styled
-- **Smart caching** — tiered refresh by session, TTL, and token usage; `SessionStart` hook pre-refreshes so new sessions never show stale data
-- **Domestic + international endpoints** — auto-detects `open.bigmodel.cn` and `api.z.ai`
-- **Zero dependencies** — no runtime deps, single-purpose CLI
+**Accurate data from official site** → **Real-time status bar display** → **Smart pacing alerts**
 
-## Quick Start
+After installation, the quota appears automatically in the Claude Code status bar:
+
+```
+GLM Lite █████████░ 91% | W ▒▒▒▒░░░░░ 47% 11:10 | 14:47 | ctx ███░░░ 45% (glm-4.7/200K)
+```
+
+**See at a glance**:
+- Plan remaining quota (91%) with progress bar
+- Weekly quota consumption (47%) + theoretical budget shadow (▒)
+- Time until reset (14:47)
+- Context window usage (45%)
+
+Auto-color alerts when pacing exceeds budget, preventing workflow interruption.
+
+## 30-Second Quick Start
 
 **One-time query (no install needed):**
 
@@ -36,20 +42,14 @@
 npx glm-quota-line
 ```
 
-**Status line integration (global install required):**
+**Status line integration (recommended):**
 
 ```bash
 npm install -g glm-quota-line
 glm-quota-line install
 ```
 
-Done. Your Claude Code status bar will now show the quota:
-
-```
-GLM Lite █████████░ 91% | W ▒▒▒▒░░░░░ 47% | 14:47 | ctx ███░░░ 45% (glm-4.7/200K)
-```
-
-You can also run `glm-quota-line` directly in the terminal to check your quota without launching Claude Code.
+Done. You can run `glm-quota-line` anytime in the terminal to check usage without launching Claude Code.
 
 Upgrade:
 
@@ -58,73 +58,41 @@ npm install -g glm-quota-line
 glm-quota-line check-update
 ```
 
-## Configuration
-
-All options are optional. Persist with `glm-quota-line config set`, or override per-invocation with CLI flags.
+## Common Workflows
 
-### style — Output layout
-
-| Value | Description | Example |
-|---|---|---|
-| `bar` (default) | Progress bar | `GLM Lite █████████░ 91% \| W ▒▒▒▒░░░░░ 47% \| 14:47 \| ctx ███░░░ 45%` |
-| `text` | Full text | `GLM Lite \| 5h 91% \| week 47% \| reset 14:47 \| ctx 45%` |
-| `compact` | Compact mode | `GLM 5h 91% W 47% \| 14:47` |
+### 📊 Quick quota check
 
 ```bash
-glm-quota-line config set style compact
+glm-quota-line
 ```
 
-### theme — Color theme
+### 🎨 Customize status bar style
 
-| Value | Description |
-|---|---|
-| `dark` (default) | Dark terminal, light pine-green accents |
-| `light` | White/light terminal, teal-blue accents |
-| `mono` | Grayscale, minimal distraction |
+**Recommended**: Use interactive configuration with live preview
 
 ```bash
-glm-quota-line config set theme light
-```
-
-Quota percentage colors change automatically based on remaining amount:
-
-- Green — remaining >= 60%
-- Yellow — remaining 30%–60%
-- Red — remaining < 30%
-
-### display — Quota metric
-
-| Value | Description |
-|---|---|
-| `left` (default) | Show remaining quota (bar fills with remaining) |
-| `used` | Show used quota (bar fills with used) |
-
-```bash
-glm-quota-line config set display used
+glm-quota-line configure
 ```
 
-### work-days — Work days per week
+For manual configuration, see [Quick Customization](#quick-customization)
 
-Set the number of work days per week (1–7) for weekly quota theoretical budget and pacing analysis. Default: 5.
+### 🤖 Change model or adjust context window
 
 ```bash
-glm-quota-line config set work-days 6
+# When Zhipu releases a new model, no need to wait for npm updates — write the local overlay immediately:
+glm-quota-line model set glm-5.3 400K
+# View all models and their context window sizes
+glm-quota-line model list
 ```
 
-Pacing analysis calculates theoretical budget based on elapsed work days:
-- Green — usage speed ≤ 1.1x theoretical
-- Yellow — usage speed 1.1x–1.3x theoretical
-- Red — usage speed > 1.3x theoretical
-
-### --json — JSON output
-
-Output structured JSON format (terminal mode only, ignored in status line mode):
+### 🔧 Script integration
 
 ```bash
 glm-quota-line --json
 ```
 
-Example output:
+Outputs structured JSON data:
+
 ```json
 {
   "level": "Lite",
@@ -134,12 +102,6 @@ Example output:
       "leftPercent": 91,
       "usedPercent": 9,
       "nextResetTime": 1715257200000
-    },
-    {
-      "label": "week",
-      "leftPercent": 47,
-      "usedPercent": 53,
-      "nextResetTime": 1715744400000
     }
   ],
   "mcp": {
@@ -149,29 +111,83 @@ Example output:
 }
 ```
 
-### minimalist — Minimal mode
+### ⚠️ Quota exhausted or display issues
 
-Hide all labels, show only progress bars and values.
+See [Troubleshooting](#troubleshooting)
+
+## Quick Customization
+
+### Recommended: Interactive configuration
+
+```bash
+glm-quota-line configure  # Live preview, WYSIWYG
+```
+
+**Key bindings**:
+- `↑↓` select component, `Enter` to edit, `Tab` to cycle style, `Space` to toggle
+- `g` for global options (theme, display mode, minimalist, raw-values, reset format)
+- `s` to save, `q` to quit
+
+### Common config (non-interactive)
+
+#### Style & theme
+
+```bash
+glm-quota-line config set style compact  # Compact mode
+glm-quota-line config set theme light    # Light theme
+glm-quota-line config set theme mono     # Grayscale minimal
+```
+
+**Style comparison**:
+
+| Style | Description | Example |
+|---|---|---|
+| `bar` (default) | Progress bar | `GLM Lite █████████░ 91% \| W ▒▒▒▒░░░░░ 47% 11:10 \| 14:47 \| ctx ███░░░ 45%` |
+| `text` | Full text | `GLM Lite \| 5h 91% \| week 47% 11:10 \| reset 14:47 \| ctx 45%` |
+| `compact` | Compact mode | `GLM 5h 91% W 47% 11:10 \| 14:47` |
+
+#### Display options
 
 ```bash
-glm-quota-line config set minimalist true
+glm-quota-line config set display used           # Show used instead of remaining
+glm-quota-line config set reset-format countdown  # Countdown mode (e.g., reset 52m)
+glm-quota-line config set minimalist true         # Hide label text
 ```
 
-Effect:
-- Off: `GLM Lite █████████░ 91% | W ▒▒▒▒░░░░░ 47% | 14:47`
-- On: `█████████░ 91% | ▒▒▒▒░░░░░ 47% | 14:47`
+**Color logic**:
 
-### raw-values — Raw values
+Quota percentage auto-colors based on remaining amount:
+- 🟢 Green — remaining >= 60%
+- 🟡 Yellow — remaining 30%–60%
+- 🔴 Red — remaining < 30%
 
-Hide all labels and show raw values directly.
+Pacing analysis auto-colors based on usage speed:
+- 🟢 Green — usage speed ≤ 1.1x theoretical
+- 🟡 Yellow — usage speed 1.1x–1.3x theoretical
+- 🔴 Red — usage speed > 1.3x theoretical
+
+<details>
+<summary><b>Advanced configuration options</b> (click to expand)</summary>
+
+### Work days setting
+
+Set the number of work days per week (1–7) for weekly quota theoretical budget and pacing analysis. Default: 5.
+
+```bash
+glm-quota-line config set work-days 6
+```
+
+### Raw values mode
+
+Display raw values directly, without percentages.
 
 ```bash
 glm-quota-line config set raw-values true
 ```
 
-### auth-token / base-url — Custom auth
+### Custom authentication
 
-If Claude Code runs behind a gateway or proxy and the injected `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_BASE_URL` are not the real values:
+If Claude Code runs behind a gateway or proxy, you can override auth credentials:
 
 ```bash
 glm-quota-line config set auth-token <your-real-token>
@@ -182,26 +198,91 @@ glm-quota-line config set base-url https://api.z.ai/api/anthropic
 
 Clear with `glm-quota-line config unset auth-token` / `base-url`.
 
-Auth source priority (highest to lowest):
-
+**Auth priority** (highest to lowest):
 1. Values persisted via `config set`
 2. Environment variables `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_BASE_URL`
 3. `env` field in `~/.claude/settings.json`
 
-### configure — Interactive TUI setup
+### Factory reset
 
-Launch a terminal UI with live preview to adjust component toggles, styles, and global options.
+One-shot reset of user config. Install state is preserved (status line/hook not removed).
 
 ```bash
-glm-quota-line configure
+glm-quota-line config reset            # Reset all user config (interactive confirm)
+glm-quota-line config reset --models   # Reset only custom model mappings (modelMap)
+glm-quota-line config reset --yes      # Skip confirmation (scripts/CI)
 ```
 
-Key bindings:
-- `↑↓` select component, `Enter` to edit, `Tab` to cycle style, `Space` to toggle
-- `g` to enter global options (theme, display mode, minimalist, raw-values)
-- `s` to save, `q` to quit
+- Default scope: all global config, component layout, custom model mappings
+- `--models` limits reset to modelMap only; other config untouched
+- Non-interactive sessions (no TTY) require `--yes` or error out
+- After reset, status line still works — model mappings fall back to bundled defaults
+
+</details>
+
+## Advanced Features
+
+<details>
+<summary><b>Model mapping management</b> (new model support)</summary>
+
+Manage context window size mapping per model. Context window usage percentage is computed from this mapping.
+
+```bash
+glm-quota-line model list                    # List all models and their context window size
+glm-quota-line model get <model-id>          # Show the size of a given model
+glm-quota-line model set <model-id> <size>   # Set model size (e.g., 300K or 300000)
+glm-quota-line model remove <model-id>       # Remove custom mapping (built-in reverts to default)
+```
+
+**Example `list` output**:
+
+```
+glm-4.5-air  128K
+glm-4.7      200K
+glm-5-turbo  200K
+glm-5.2      1M *
+```
+
+The `*` marker indicates a user-configured mapping.
+
+**Two-layer design**:
+- Bundled `data/models.json` as default base
+- `modelMap` in `~/.claude/glm-quota-line.json` as user overlay (merged key-by-key at runtime)
+
+**Advantage**: When Zhipu releases a new model, no need to wait for npm package updates — just run `model set <new-model> <size>` to write the local overlay and it takes effect immediately.
+
+To clear all custom model mappings and return to bundled defaults: `glm-quota-line config reset --models --yes`.
+
+</details>
+
+<details>
+<summary><b>Agent / Automation interface</b></summary>
+
+If you are an AI agent (Claude Code / Cursor / Codex) or script author, the following interface is guaranteed stable:
+
+```bash
+# Get full machine-readable schema of all commands in one call
+glm-quota-line commands --json
+
+# Focused help for a single command or command group
+glm-quota-line model --help
+glm-quota-line config set --help
+```
+
+**Conventions**:
+- **Exit codes**: `0` on success, `1` on error
+- **Side-effect tags**: Each command tagged `read` (safe for automation), `write` (persists config/model map), `mutating` (modifies Claude Code integration), or `interactive` (requires TTY)
+- **Non-blocking**: No command blocks waiting for input
+- **Read query**: `glm-quota-line --json` emits structured quota data
+
+Typical agent workflow: Run `commands --json` to discover capabilities → invoke command → parse stdout.
+
+</details>
 
-Components:
+<details>
+<summary><b>Component-level control</b></summary>
+
+Through component mode in `glm-quota-line configure`, each display component can be individually toggled and styled. See [Quick Customization](#quick-customization) for key bindings; component capabilities:
 
 | Component | Description | Styleable | Hideable |
 |---|---|---|---|
@@ -211,18 +292,55 @@ Components:
 | `reset` | Reset time | — | ✓ |
 | `ctx` | Context window usage | ✓ (bar/text) | ✓ |
 
-## Recommended Combinations
+</details>
+
+## Troubleshooting
+
+### Quota not displaying
+
+**Possible causes**:
+1. Auth info missing or expired
+2. Non-GLM provider (endpoint not `open.bigmodel.cn` or `api.z.ai`)
+3. Network connection issues
+
+**Solutions**:
+```bash
+# Check auth status
+glm-quota-line
+
+# If shows "auth expired", update auth info
+glm-quota-line config set auth-token <your-token>
+glm-quota-line config set base-url https://open.bigmodel.cn/api/anthropic
+```
+
+### Shows "quota unavailable"
+
+**Possible causes**:
+- Zhipu API interface issues
+- Network connection problems
+
+**Solutions**:
+- Retry later (tool auto-retries)
+- Check network connection
+- If persistent, may be Zhipu service issues
+
+### Install/uninstall issues
 
-| Use case | Config |
-|---|---|
-| Dark terminal (default) | `style=bar`, `theme=dark` |
-| Light terminal | `style=bar`, `theme=light` |
-| Minimal setup | `style=compact`, `theme=mono` |
-| Track usage | `style=bar`, `display=used` |
-| Scripting | `--json` |
-| 6-day work week | `work-days=6` |
-| Minimal values | `minimalist=true` |
-| Interactive setup | `glm-quota-line configure` |
+**Status bar not updating**:
+```bash
+glm-quota-line uninstall
+glm-quota-line install --force
+```
+
+`install --force` backs up previous config; `uninstall` restores when possible.
+
+### Debug mode
+
+Set `GLM_QUOTA_DEBUG=1` to output context window debug info to stderr:
+
+```bash
+GLM_QUOTA_DEBUG=1 glm-quota-line
+```
 
 ## Command Reference
 
@@ -234,23 +352,27 @@ glm-quota-line version
 glm-quota-line check-update
 glm-quota-line configure
 glm-quota-line config show
-glm-quota-line config set <style|display|theme|auth-token|base-url|work-days|minimalist|raw-values> <value>
+glm-quota-line config set <style|display|theme|auth-token|base-url|work-days|minimalist|raw-values|reset-format> <value>
 glm-quota-line config unset <key>
+glm-quota-line config reset [--models] [--yes]
+glm-quota-line model list
+glm-quota-line model get <model-id>
+glm-quota-line model set <model-id> <size>
+glm-quota-line model remove <model-id>
+glm-quota-line commands --json
 ```
 
 Run `glm-quota-line --help` for full descriptions.
 
-## Notes
+## Technical Notes
 
 - Shows `TOKENS_LIMIT` and `MCP_LIMIT` / `TIME_LIMIT` quotas
-- Weekly quota progress bar shadow (▒) is a daily pacing baseline: the theoretical budget based on elapsed work days — the more the filled bar (█) extends past the shadow, the faster you're consuming
-- Context window usage is shown by default; toggle via `glm-quota-line configure`
-- Context window usage is calculated from raw tokens when model mapping is available, falls back to API-provided percentages
-- Each component can be individually toggled and styled via `glm-quota-line configure`
-- 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
-- Set `GLM_QUOTA_DEBUG=1` to output context window debug info to stderr
+- Weekly quota progress bar shadow (▒) is the daily pacing baseline: theoretical budget based on elapsed work days
+- Context window usage computed from raw tokens using local model map; falls back to API-provided percentage when mapping unavailable
+- Smart caching: tiered refresh by session, TTL, and token usage; `SessionStart` hook pre-refreshes so new sessions never show stale data
+- Auto-detects domestic (`open.bigmodel.cn`) and international (`api.z.ai`) endpoints
+- Non-GLM providers automatically disable quota queries
+- Zero runtime dependencies
 
 ## License