ccgauge 1.0.2 → 1.0.3

package/CHANGELOG.md

@@ -5,6 +5,153 @@ All notable changes to **ccgauge** are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.3] — 2026-05-15
+
+A focused **MCP server** correctness + performance + ergonomics pass,
+plus a docs catch-up for the marketing site and the bundled READMEs.
+Dashboard runtime is unchanged from 1.0.2. The MCP server adds a 9th
+tool (`cost_estimator`), gets ~4× faster on weekly summaries, halves
+its bundle size, and ships a `ccgauge mcp --check` self-test.
+
+### Highlights
+
+- **9 MCP tools** — added `cost_estimator(source, model, input_tokens,
+  output_tokens, …)` for pure pricing what-ifs (no record lookup).
+  Pairs with `usage_summary` for "if I run X more on Opus 4.7, what
+  does it add to my month-to-date?".
+- **`weekly_summary` is ~4× faster.** Rewrote the per-day trend from
+  8 full record-set passes (1 totals + 7 daily totals × 2 internal
+  source filters) down to a single `timeBuckets('day')` call + a
+  7-slot skeleton merge. Same JSON shape out, including zero-fill
+  for empty days.
+- **MCP bundle 810 KB → 379 KB.** esbuild `minify: true` +
+  `external: ['fsevents']` shaves 53% off the published tarball's
+  MCP slice with no runtime behaviour change.
+- **`ccgauge mcp --check`** — verifies the bundle, boots the indexer,
+  and prints one line per provider (files / records / scanned dirs).
+  Lets users debug "Claude Desktop doesn't see ccgauge tools"
+  without spinning up an MCP client first.
+
+### Added
+
+- `cost_estimator` MCP tool — uses the provider's built-in
+  per-1M-token pricing table; does NOT consult usage history.
+  Useful for budgeting and cap planning.
+- `ccgauge mcp --check` self-test command.
+- README cross-references for both new entry points (`mcp --check`,
+  `cost_estimator`) in en + zh.
+- `__SERVER_VERSION__` injected by esbuild from `package.json#version`
+  so the server's MCP handshake always agrees with the npm release.
+
+### Changed
+
+- **`ccgauge mcp` runs in-process.** The CLI subcommand used to
+  spawn a second Node process for the bundled server (`spawn(node,
+  [bundle])`); it now `await import()`s the bundle and calls
+  `runStdioServer()` directly. Saves ~80–150 ms per invocation and
+  removes a brittle signal-forwarding shim.
+- **MCP responses are compact JSON.** Drop the `JSON.stringify(...,
+  null, 2)` pretty-print on every tool response — LLMs don't read
+  indentation but pay for it. ~30–50% smaller responses for the
+  heavier tools (`weekly_summary`, `usage_by_session`).
+  `CCGAUGE_MCP_PRETTY=1` re-enables.
+- **Default limits on `usage_by_model` (20) and `usage_by_project`
+  (20).** The cap existed as a max; the default is now the same
+  value. A user asking "what did I work on this year" with hundreds
+  of projects no longer gets a 200-entry payload.
+- **`recent_activity` defaults to a 30-day window** (`days` arg to
+  widen). Previously aggregated every session across the user's
+  full CLI lifetime just to return the top 10 by `end_time` — cost
+  grew linearly with history.
+- **Day-aligned named ranges.** `7d` / `30d` / `90d` now map to
+  `[start-of(N-1 days ago), end-of-today]` like `today` /
+  `yesterday` / `this_week` already did. Previously `7d` was a
+  rolling 7×24h window, so summing seven `daily_summary` calls
+  didn't equal one `usage_summary({range:"7d"})` — they do now.
+- **README Highlights refreshed** (en + zh). New top-level subsections
+  for `ccgauge report` (CLI) and `ccgauge mcp` (MCP server) so the
+  two no-server entry points are visible in the first scroll.
+  Cross-provider section updated for 1.0.2's tri-state switcher +
+  real provider logos + worktree-aware Projects collapsing.
+  Drill-down section mentions the Tokens / Conversations trend toggle.
+
+### Fixed
+
+- **`parseDateLike` no longer accepts calendar-overflow dates with
+  a time suffix.** `2026-02-31T00:00:00` used to silently roll
+  forward to March 3 (JS `new Date()` normalises invalid dates);
+  now both the bare-date branch and the time-suffix branch reject
+  it. Affects every MCP date arg, the dashboard's `from`/`to` URL
+  params, and `ccgauge report --since`/`--until`.
+- **`SERVER_VERSION` no longer hardcoded** to `0.4.0`. Now sourced
+  from `package.json#version` at bundle time, so the MCP server's
+  `initialize` response reports the same version as the npm release
+  it shipped in.
+- **README `range: "14d"` example was bogus** — the schema enum
+  doesn't accept `14d`, so following the README's project-breakdown
+  prompt produced an error. Replaced with the explicit-`from`/`to`
+  form. Same fix in `README.zh-CN.md`.
+
+### Performance
+
+| Metric | Before | After |
+| --- | --- | --- |
+| `dist/mcp/server.mjs` size | 810 KB | **379 KB** (-53%) |
+| `weekly_summary` record-set passes | 8 (+ 2 internal source filters each) | **2** |
+| `recent_activity` aggregation scope | every session ever | **last 30 days** |
+| MCP response JSON byte count (typical) | indented | **~half** |
+| Aggregator `withinRange` Date#toISOString() calls | per record × N filters | **once per call** |
+
+### Security / privacy
+
+- **MCP tool errors are scrubbed of `$HOME` paths** before they
+  reach the SDK's error envelope. Belt-and-suspenders today (the
+  only user-visible throws are clean date-arg validators), but
+  defends against future error paths that might wrap an indexer
+  error. Extracted the existing `sanitizeForUser` from the indexer
+  module into a shared `lib/sanitize` so both layers use one
+  definition.
+
+### Internal
+
+- `lib/aggregator/index.ts` — entry-point functions now hoist
+  `from/to → ISO string` and `models/projects → Set` once per
+  call instead of recomputing them per record. Measurable on the
+  `weekly_summary` hot path; invisible for the dashboard's
+  single-pass aggregators.
+- New `lib/mcp/text-result.ts` — single source of truth for the
+  MCP response wrapper. `lib/mcp/safe-handler.ts` — HOF that wraps
+  tool callbacks with the path-scrub guard.
+- `parseDayArg` moved from `tools/activity.ts` to `mcp/context.ts`
+  next to `parseDateRange` so the two share a single implementation
+  of the "today / yesterday / monday / YYYY-MM-DD" parser.
+- 30 s polling fallback in the indexer is now **off by default for
+  the MCP instance** and **on by default for the dashboard**.
+  Override with `CCGAUGE_POLL_FALLBACK={0,1}`. The MCP server runs
+  in a background daemon spawned by an LLM client and shouldn't
+  keep the host warm just to catch the rare `fs.watch(recursive)`
+  miss.
+- `AGENTS.md` documents the `site/` sub-project, the v4 sidechain
+  merge invariant, a release checklist, and the
+  `raw.githubusercontent.com` hero-image fragility. Two new
+  "intentionally NOT supported" items: folding `site/` into a pnpm
+  workspace, and letting `site/` leak into the npm tarball.
+
+### Docs (doesn't ship to npm)
+
+- Marketing site (`site/`) catches up to 1.0.2: features page
+  covers All view + conversation-count toggle + worktree merging;
+  homepage hero, "Multi-source analytics" card, and ScreenshotFrame
+  now use three distinct screenshots; hardcoded `v1.0.0` eyebrows
+  removed.
+- `site/public/images/README.md` rewritten as a single-source-of-
+  truth inventory (file → used-by → source), with the prompt
+  catalogue trimmed to filenames that actually exist. Legacy
+  placeholder SVGs moved to an explicit "kept but unused"
+  subsection.
+- `site/public/robots.txt` no longer points at a non-existent
+  `sitemap-index.xml`.
+
 ## [1.0.2] — 2026-05-15
 
 This release brings the dashboard the long-requested **All view** (one
@@ -531,6 +678,7 @@ of HTML to the browser.
 - Initial public release as `ccgauge`: local Next.js dashboard for
   Claude Code token usage, cost, and 5-hour block tracking.
 
+[1.0.3]: https://github.com/chengzuopeng/ccgauge/compare/v1.0.2...v1.0.3
 [1.0.2]: https://github.com/chengzuopeng/ccgauge/compare/v1.0.1...v1.0.2
 [1.0.1]: https://github.com/chengzuopeng/ccgauge/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/chengzuopeng/ccgauge/compare/v0.4.0...v1.0.0

package/README.md

@@ -38,8 +38,9 @@ Everything runs locally as a Next.js app. Your conversation transcripts never le
 ## Highlights
 
 ### Cross-provider analytics
-- One dashboard for both **Claude Code** and **OpenAI Codex CLI**
-- Toggle data source from the nav bar; URL persists via `?source=`, last choice cached in cookie
+- One dashboard for both **Claude Code** and **OpenAI Codex CLI**, plus an **All view** that merges the two
+- Toggle data source from the nav bar (Claude · Codex · All), each button rendered with the real provider logo; URL persists via `?source=`, last choice cached in cookie
+- **Worktree-aware Projects** — all worktrees of the same repo collapse into a single project row
 - Built-in **provider adapter layer** (`lib/providers/`) — adding a third CLI (Gemini CLI, Cursor, Aider, …) is one new file plus a single registry line
 
 ### At-a-glance KPIs
@@ -51,7 +52,7 @@ Everything runs locally as a Next.js app. Your conversation transcripts never le
 - **Sessions** — per-conversation list with model / tokens / cost / duration, plus a message-level timeline
 - **Projects** — per-`cwd` aggregation cards with sparkline and spend share
 - **Models** — side-by-side comparison: cost share, tokens share, cache hit, USD pricing
-- **Usage** — turn-grouped table with expandable tool-call breakdown, CSV export
+- **Usage** — turn-grouped table with expandable tool-call breakdown, CSV export. **Tokens / Conversations** toggle on the trend chart so you can count rows the way the usage table counts them
 
 ### Cost transparency
 - **Cache savings** is its own KPI — quantifies how much Anthropic prompt caching saved you vs. paying full input price
@@ -63,6 +64,17 @@ Everything runs locally as a Next.js app. Your conversation transcripts never le
 - **English / 中文** (cookie + localStorage)
 - Filters: time range (today / 7d / 30d / 90d / all), granularity (hour / day / week / month), model and project multi-select
 
+### CLI report (no server)
+- `ccgauge report` prints a colored, aligned terminal usage report in ~0.2 s from the same JSONL the dashboard reads
+- `--range / --source / --by / --since / --until / --model / --project` filters
+- `--json` for machine-readable output; `--no-color` auto-applied when piped — drops cleanly into shell scripts and CI
+
+### MCP server (for LLMs)
+- `ccgauge mcp` runs a stdio JSON-RPC server so **Claude Desktop / Cursor / Cline** can query your local usage directly
+- Nine MCP tools: `usage_summary`, `usage_by_time`, `usage_by_model`, `usage_by_project`, `usage_by_session`, `daily_summary`, `weekly_summary`, `recent_activity`, `cost_estimator`
+- Reasoning-token breakdown surfaced for the models that emit one
+- Separate named cache (`index-mcp-v2.json`) so MCP runs don't contend with the dashboard
+
 ### Privacy by design
 - 100 % local: read-only access to existing JSONL files, zero outbound network calls
 - Open source, MIT-licensed
@@ -217,6 +229,7 @@ English with real numbers from your machine.
 | `daily_summary` | "What did I do today / yesterday / Monday / on YYYY-MM-DD?" Sessions grouped by project + models + top tool calls. |
 | `weekly_summary` | 7-day roll-up: per-day cost trend, top sessions, top projects, models. `week_offset=-1` for last week. |
 | `recent_activity` | The N most recently active sessions across providers. |
+| `cost_estimator` | Compute the USD cost of a hypothetical request (`{ source, model, input_tokens, output_tokens, cache_* }`). Uses built-in per-1M-token pricing; does NOT consult usage history. |
 
 | Resource URI | Content |
 | --- | --- |
@@ -334,8 +347,8 @@ debug "why did it answer X".
   → `daily_summary({ date: "yesterday" })`
 - *"Generate a Monday stand-up bullet list of what I shipped last week."*
   → `weekly_summary({ week_offset: -1 })`
-- *"Which 3 projects have I touched most in the last 2 weeks?"*
-  → `usage_by_project({ range: "14d", limit: 3 })` (LLM may also pull `weekly_summary`)
+- *"Which 3 projects have I touched most in the last two weeks?"*
+  → `usage_by_project({ from: "2026-05-01", to: "2026-05-15", limit: 3 })` — pass explicit `from`/`to` for any window not covered by the named ranges (`7d` / `30d` / `90d` / `this_week` / `last_week` / …).
 - *"What was my last coding session about?"*
   → `recent_activity({ limit: 1 })`
 
@@ -351,7 +364,7 @@ debug "why did it answer X".
 - *"At my current burn rate, how much will I spend this month?"*
   → `usage_summary({ range: "this_month" })` + `usage_by_time({ range: "this_month", granularity: "day" })` — LLM extrapolates.
 - *"If I run another 200K input + 50K output on Opus 4.7 today, what does that add to my month-to-date cost?"*
-  → `usage_summary({ range: "this_month" })` + LLM does the arithmetic from the published per-1M-token rates.
+  → `cost_estimator({ source: "claude", model: "claude-opus-4-7", input_tokens: 200000, output_tokens: 50000 })` + `usage_summary({ range: "this_month" })` — the estimator returns the dollar cost for the hypothetical request without touching your usage history.
 
 #### Cross-source comparisons
 

package/README.zh-CN.md

@@ -38,8 +38,9 @@ npx ccgauge
 ## 亮点
 
 ### 多 CLI 数据源
-- 一份看板覆盖 **Claude Code** 与 **OpenAI Codex CLI**
-- 顶部一键切换，URL 用 `?source=` 持久化，cookie 记忆上次选择
+- 一份看板覆盖 **Claude Code** 与 **OpenAI Codex CLI**，并提供 **All 视图**把两者合并查看
+- 顶部三档切换（Claude · Codex · All），每个按钮都带真品牌 logo；URL 用 `?source=` 持久化，cookie 记忆上次选择
+- **Worktree 感知的 Projects 合并** —— 同一个 repo 的所有 worktree 自动并到同一个项目行
 - 内置 **Provider 适配层**（`lib/providers/`）—— 增加第三个 CLI（Gemini CLI / Cursor / Aider …）只需一个新文件加注册表一行
 
 ### KPI 一眼看完
@@ -51,7 +52,7 @@ npx ccgauge
 - **会话页** —— 每场对话单独成行（模型 / token / 花费 / 时长），点进去看消息级时间线
 - **项目页** —— 按 `cwd` 聚合成卡片网格，含趋势条与花费占比
 - **模型页** —— 各模型并排对比：成本占比、token 占比、缓存命中、官方单价
-- **用量页** —— 按对话轮次分组的明细表，可展开看每次工具调用，支持 CSV 导出
+- **用量页** —— 按对话轮次分组的明细表，可展开看每次工具调用，支持 CSV 导出。趋势图支持 **Token / 对话数** 切换，让条形图行数和用量表 1:1 对齐
 
 ### 成本透明
 - **缓存节省** 单独成卡 —— 量化 Anthropic prompt caching 实际帮你节省了多少美元
@@ -63,6 +64,17 @@ npx ccgauge
 - **English / 中文** 双语，cookie + localStorage 双向同步
 - 完整筛选：时间区间（今天 / 7 天 / 30 天 / 90 天 / 全部）、粒度（小时 / 天 / 周 / 月）、模型 / 项目 multi-select
 
+### 命令行报告（无 server）
+- `ccgauge report` 读取同一份 JSONL，在 ~0.2 秒内打出彩色对齐的终端报告
+- `--range / --source / --by / --since / --until / --model / --project` 滤波参数
+- `--json` 输出给脚本；`--no-color` 走管道时自动开启 —— 可以直接塞进 shell 和 CI
+
+### MCP 服务（给 LLM 用）
+- `ccgauge mcp` 起一个 stdio JSON-RPC 服务，让 **Claude Desktop / Cursor / Cline** 等 MCP 客户端直接查你本地的 ccgauge 历史
+- 9 个 MCP tool：`usage_summary`、`usage_by_time`、`usage_by_model`、`usage_by_project`、`usage_by_session`、`daily_summary`、`weekly_summary`、`recent_activity`、`cost_estimator`
+- 支持模型有 reasoning token 时单独折算
+- 独立命名缓存（`index-mcp-v2.json`），MCP 进程不会和仪表盘抢同一份磁盘索引
+
 ### 隐私优先
 - 100 % 本地：只读访问已有 JSONL 文件，零外网调用
 - 开源，MIT 协议
@@ -213,7 +225,8 @@ LLM 会自动选合适的 tool、本地调用、用大白话给你带真实数
 | `usage_by_session` | 会话列表，含标题（首条用户消息）/ 模型 / 时长 / 花费。可按 recent / cost / tokens / duration 排序。 |
 | `daily_summary` | "今天 / 昨天 / 周一 / YYYY-MM-DD 我都干了啥？" 按项目分组的会话 + 模型 + top 工具调用。 |
 | `weekly_summary` | 7 天 roll-up：每日花费趋势 + top 会话 + top 项目 + 模型分布。`week_offset=-1` 看上周。 |
-| `recent_activity` | 最近 N 条活跃会话（不限日期）。 |
+| `recent_activity` | 最近 N 条活跃会话（默认最近 30 天，可显式给 `from`/`to`）。 |
+| `cost_estimator` | 计算"假设我用 X 模型发 N 个 token 要花多少钱"。直接读内置 per-1M-token 单价表，不查历史。常用于额度规划 / what-if。 |
 
 | Resource URI | 内容 |
 | --- | --- |
@@ -329,7 +342,7 @@ LLM 大概率会调的工具——方便你"为什么会这样回答"反查。
 - *"给我一份周一 standup 用的 bullet list，列我上周完成的事。"*
   → `weekly_summary({ week_offset: -1 })`
 - *"过去两周我接触最多的 3 个项目是什么？"*
-  → `usage_by_project({ range: "14d", limit: 3 })`（LLM 也可能补一次 `weekly_summary`）
+  → `usage_by_project({ from: "2026-05-01", to: "2026-05-15", limit: 3 })`——非 `7d` / `30d` / `90d` / `this_week` / `last_week` 等命名窗口时，传显式 `from` / `to`。
 - *"我最近一次的编码会话是关于什么的？"*
   → `recent_activity({ limit: 1 })`
 
@@ -345,7 +358,7 @@ LLM 大概率会调的工具——方便你"为什么会这样回答"反查。
 - *"按当前消耗速度，本月预计花多少？"*
   → `usage_summary({ range: "this_month" })` + `usage_by_time({ range: "this_month", granularity: "day" })`——LLM 自己外推。
 - *"如果我今天再在 Opus 4.7 上跑 200K input + 50K output，本月累计要多少？"*
-  → `usage_summary({ range: "this_month" })` + LLM 按公开单价做算术。
+  → `cost_estimator({ source: "claude", model: "claude-opus-4-7", input_tokens: 200000, output_tokens: 50000 })` + `usage_summary({ range: "this_month" })`——estimator 直接按内置单价表返回这笔假设请求的美元成本，不查历史。
 
 #### 跨数据源对比
 

package/bin/cli.mjs

@@ -142,8 +142,9 @@ program
 program
   .command('mcp')
   .description('start the MCP server (stdio) so LLMs can query usage data')
-  .action(async () => {
-    await startMcp();
+  .option('--check', 'verify the bundle + indexer; print one line per provider and exit')
+  .action(async (opts) => {
+    await startMcp(opts);
   });
 
 function addReportOptions(cmd) {
@@ -438,7 +439,7 @@ or run the full build with
   }
 }
 
-async function startMcp() {
+async function startMcp(opts = {}) {
   const bundle = join(packageRoot, 'dist', 'mcp', 'server.mjs');
   if (!existsSync(bundle)) {
     console.error(`
@@ -455,20 +456,39 @@ or run the full build with
 `);
     process.exit(1);
   }
-  // Hand control to the bundled MCP server. It owns the stdio JSON-RPC
-  // session for the lifetime of the parent (the LLM client) process.
-  const child = spawn(process.execPath, [bundle], {
-    stdio: 'inherit',
-    env: process.env,
-  });
-  const forward = (sig) => () => {
-    if (!child.killed) child.kill(sig);
-  };
-  process.on('SIGINT', forward('SIGINT'));
-  process.on('SIGTERM', forward('SIGTERM'));
-  child.on('exit', (code, sig) => {
-    process.exit(typeof code === 'number' ? code : sig ? 128 : 0);
-  });
+
+  // --check: don't actually run the JSON-RPC server — load the bundle,
+  // boot the indexer, print one line per provider, and exit. Lets users
+  // verify their install without wiring up an MCP client.
+  if (opts.check) {
+    const mod = await import(pathToFileURL(bundle).href);
+    if (typeof mod.printCheck !== 'function') {
+      console.error('[ccgauge-mcp] this bundle was built without --check support');
+      process.exit(1);
+    }
+    const code = await mod.printCheck();
+    process.exit(typeof code === 'number' ? code : 0);
+  }
+
+  // Run the bundled MCP server **in this process** — the bundle exposes a
+  // top-level `runStdioServer()` so we just import + invoke it. Spawning a
+  // second Node process here is wasted memory/latency (LLM clients already
+  // spawn `ccgauge mcp` per conversation), and forwarding signals across
+  // processes is brittle (e.g. SIGHUP isn't covered by the old shim).
+  try {
+    const mod = await import(pathToFileURL(bundle).href);
+    if (typeof mod.runStdioServer !== 'function') {
+      console.error('[ccgauge-mcp] bundle missing runStdioServer export');
+      process.exit(1);
+    }
+    await mod.runStdioServer();
+    // runStdioServer keeps the loop alive via the stdio transport; if it
+    // ever returns it means the transport closed cleanly.
+    process.exit(0);
+  } catch (err) {
+    console.error('[ccgauge-mcp] failed to start:', err?.message ?? err);
+    process.exit(1);
+  }
 }
 
 async function resolvePort(opts) {