vibeusage 0.2.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 victor-wu.eth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,182 @@
+<div align="center">
+
+# 🟢 VIBESCORE
+
+**QUANTIFY YOUR AI OUTPUT**  
+_Real-time AI Analytics for Codex CLI_
+
+[**www.vibeusage.cc**](https://www.vibeusage.cc)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Support](https://img.shields.io/badge/Node.js-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+[![Platform](https://img.shields.io/badge/Platform-macOS-lightgrey.svg)](https://www.apple.com/macos/)
+
+[**English**](README.md) • [**中文说明**](README.zh-CN.md)
+
+[**Documentation**](docs/) • [**Dashboard**](dashboard/) • [**Backend API**](BACKEND_API.md)
+
+<br/>
+
+<img src="docs/screenshots/dashboard.png" width="900" alt="VibeUsage Dashboard Preview"/>
+
+</div>
+
+---
+
+## 🌌 Overview
+
+**VibeUsage** is an intelligent token usage tracking system designed specifically for macOS developers. Through the all-new **Matrix-A Design System**, it provides a high-fidelity cyberpunk-style dashboard that transforms your **AI Output** into quantifiable metrics, supported by the **Neural Divergence Map** for real-time monitoring of multi-model compute distribution.
+
+> [!TIP] > **Core Index**: Our signature metric that reflects your flow state by analyzing token consumption rates and patterns.
+
+## 🔒 Privacy-First Architecture (Stealth Protocol)
+
+We believe your code and thoughts are your own. VibeUsage is built with strict privacy pillars to ensure your data never leaves your control.
+
+- 🛡️ **No Content Upload**: We never upload prompts or responses. We only compute token counts locally and send counts plus minimal metadata (timestamps, model, device).
+- 📡 **Local Aggregation**: All token consumption analysis happens on your machine. We only relay quantized 30-minute usage buckets to the cloud.
+- 🔐 **Hashed Identity**: Device tokens are hashed using SHA-256 server-side. Your raw credentials never exist in our database.
+- 🔦 **Full Transparency**: Audit the sync logic yourself in `src/lib/rollout.js`. We literally only capture numbers and timestamps.
+
+## 🚀 Key Features
+
+- 📡 **Auto-Sync**: Real-time interception of Codex CLI pipes with **automatic background synchronization**. Once initialized, your tokens are tracked and synced without any manual commands.
+- 🧭 **Universal-Sync**: Native support for **Codex CLI**, **Every Code**, and the latest **Claude Code**. Whether it's GPT-4, Claude 3.5 Sonnet, or o1/Gemini, token consumption from all models is unified and counted.
+- 📊 **Matrix Dashboard**: High-performance dashboard built with React + Vite, featuring the new **Matrix-A** design language.
+  - **Neural Divergence Map**: Visualize multi-engine load balancing and compute distribution.
+  - **Cost Intelligence**: Real-time, multi-dimensional cost breakdown and forecasting.
+  - **Smart Notifications**: Non-intrusive system-level alerts using a Golden (Gold/Amber) visual style for high-value information.
+- ⚡ **AI Analytics**: Deep analysis of Input/Output tokens, with dedicated tracking for Cached and Reasoning components.
+- 🔒 **Identity Core**: Robust authentication and permission management to secure your development data.
+
+### 🌌 Visual Preview
+
+<img src="docs/screenshots/landing.png" width="900" alt="VibeUsage Landing Preview"/>
+
+## 🛠️ Quick Start
+
+### Installation
+
+Initialize your environment once and forget it. VibeUsage handles all synchronization in the background automatically.
+
+```bash
+npx --yes vibeusage init
+```
+
+Note: `init` shows a consent prompt in interactive shells. Use `--yes` to skip prompts in non-interactive environments.
+Optional: `--dry-run` previews planned changes without writing files.
+Note: If `~/.code/config.toml` exists (or `CODE_HOME`), `init` also configures Every Code `notify` automatically. No further user intervention is required for data sync.
+Note: If Gemini CLI home exists, `init` installs a `SessionEnd` hook in `~/.gemini/settings.json` and sets `tools.enableHooks = true` so hooks execute. This enables all Gemini hooks; disable by setting `tools.enableHooks = false` (or disabling the `vibeusage-tracker` hook).
+
+### Sync & Status
+
+````bash
+While sync happens automatically, you can manually trigger a synchronization or check status anytime:
+
+```bash
+# Manually sync latest local session data (Optional)
+npx --yes vibeusage sync
+
+# Check current link status
+npx --yes vibeusage status
+````
+
+### Sources
+
+- Codex CLI logs: `~/.codex/sessions/**/rollout-*.jsonl` (override with `CODEX_HOME`)
+- Every Code logs: `~/.code/sessions/**/rollout-*.jsonl` (override with `CODE_HOME`)
+- Gemini CLI logs: `~/.gemini/tmp/**/chats/session-*.json` (override with `GEMINI_HOME`)
+
+## 🔧 Environment Variables
+
+- `VIBESCORE_HTTP_TIMEOUT_MS`: CLI HTTP timeout in ms (default `20000`, `0` disables, clamped to `1000..120000`).
+- `VITE_VIBESCORE_HTTP_TIMEOUT_MS`: Dashboard request timeout in ms (default `15000`, `0` disables, clamped to `1000..30000`).
+- `GEMINI_HOME`: Override Gemini CLI home (defaults to `~/.gemini`).
+
+## 🧰 Troubleshooting
+
+### Streak shows 0 days while totals look correct
+
+- Streak is defined as consecutive days ending today. If today's total is 0, streak will be 0.
+- If you expect a non-zero streak, clear cached auth/heatmap data and sign in again:
+
+```js
+localStorage.removeItem("vibeusage.dashboard.auth.v1");
+Object.keys(localStorage)
+  .filter((k) => k.startsWith("vibeusage.heatmap."))
+  .forEach((k) => localStorage.removeItem(k));
+location.reload();
+```
+
+- Complete the landing page sign-in flow again after reload.
+- Note: `insforge-auth-token` is not used by the dashboard; use `vibeusage.dashboard.auth.v1`.
+
+## 🏗️ Architecture
+
+```mermaid
+graph TD
+    A[Codex CLI] -->|Rollout Logs| B(Tracker CLI)
+    B -->|AI Tokens| C{Core Relay}
+    C --> D[VibeUsage Dashboard]
+    C --> E[AI Analytics Engine]
+```
+
+## 💻 Developer Guide
+
+To run locally or contribute:
+
+### Dashboard Development
+
+```bash
+# Install dependencies
+cd dashboard
+npm install
+
+# Start dev server
+npm run dev
+```
+
+### Debug Payload (Usage Endpoints)
+
+When `debug=1` is included in a usage endpoint request, the response adds a `debug` object that helps the dashboard attribute slow queries without relying on response headers.
+
+```ts
+const res = await fetch(
+  `${baseUrl}/functions/vibeusage-usage-summary?from=2025-12-30&to=2025-12-30&debug=1`,
+  {
+    headers: { Authorization: `Bearer ${userJwt}` }
+  }
+);
+const data = await res.json();
+
+if (data.debug) {
+  console.debug('usage debug', {
+    requestId: data.debug.request_id,
+    status: data.debug.status,
+    queryMs: data.debug.query_ms,
+    slowThresholdMs: data.debug.slow_threshold_ms,
+    slowQuery: data.debug.slow_query
+  });
+}
+```
+
+### Architecture Validation
+
+```bash
+# Validate Copy Registry
+npm run validate:copy
+
+# Run smoke tests
+npm run smoke
+```
+
+## 📜 License
+
+This project is licensed under the [MIT License](LICENSE).
+
+---
+
+<div align="center">
+  <b>System_Ready // 2024 VibeUsage OS</b><br/>
+  <i>"More Tokens. More Vibe."</i>
+</div>

package/README.zh-CN.md

@@ -0,0 +1,182 @@
+<div align="center">
+
+# 🟢 VIBESCORE
+
+**量化你的 AI 产出**  
+_Codex CLI 实时 AI 分析工具_
+
+[**www.vibeusage.cc**](https://www.vibeusage.cc)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Support](https://img.shields.io/badge/Node.js-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+[![Platform](https://img.shields.io/badge/Platform-macOS-lightgrey.svg)](https://www.apple.com/macos/)
+
+[**English**](README.md) • [**中文说明**](README.zh-CN.md)
+
+[**文档**](docs/) • [**控制台**](dashboard/) • [**后端接口**](BACKEND_API.md)
+
+<br/>
+
+<img src="docs/screenshots/dashboard.png" width="900" alt="VibeUsage 控制台预览"/>
+
+</div>
+
+---
+
+## 🌌 项目概述
+
+**VibeUsage** 是一个专为 macOS 开发者设计的智能令牌（Token）使用追踪系统。它通过全新的 **Matrix-A Design System**，提供高度可视化的赛博朋克风格仪表盘，将你的 **AI 产出 (AI Output)** 转化为可量化的指标，并支持通过 **Neural Divergence Map** 实时监控多模型的算力分布。
+
+> [!TIP] > **Core Index (核心指数)**: 我们的标志性指标，通过分析 Token 消耗速率与模式，反映你的开发心流状态。
+
+## 🔒 隐私优先架构 (隐身协议)
+
+我们坚信你的代码和思想属于你自己。VibeUsage 建立在严格的隐私支柱之上，确保你的数据始终处于受控状态。
+
+- 🛡️ **内容不出本地**：我们从不上传 Prompt 或响应内容。只在本地计算 Token 数量，并上传 Token 计数与最小元数据（时间、模型、设备）。
+- 📡 **本地聚合**：所有 Token 消耗分析均在你的机器上完成。我们仅将量化的 30 分钟使用桶（Usage Buckets）中继到云端。
+- 🔐 **身份哈希**：设备令牌在服务端使用 SHA-256 进行哈希处理。你的原始凭据绝不会存在于我们的数据库中。
+- 🔦 **全程透明**：你可以亲自审计 `src/lib/rollout.js` 中的同步逻辑。我们真正采集的只有数字和时间戳。
+
+## 🚀 核心功能
+
+- 📡 **自动嗅探与同步 (Auto-Sync)**: 实时监听 Codex CLI 管道并具备**全自动后台同步**功能。初始化后，你的 Token 产出将自动追踪并同步，无需手动执行脚本。
+- 🧭 **全能采集 (Universal-Sync)**: 原生支持 **Codex CLI**, **Every Code** 以及最新的 **Claude Code**。无论是 GPT-4, Claude 3.5 Sonnet 还是 o1/Gemini，所有模型的 Token 消耗均可被统一捕获与统计。
+- 📊 **Matrix Dashboard (矩阵控制台)**: 基于 React + Vite 的高性能仪表盘，采用全新的 **Matrix-A** 设计语言。
+  - **Neural Divergence Map (神经发散图谱)**: 可视化多引擎负载均衡状态，直观展示算力分布。
+  - **Cost Intelligence (成本智能)**: 实时、多维度的成本分解与预测。
+  - **Smart Notifications (智能通知)**: 非侵入式的系统级通知，采用金色 (Gold/Amber) 视觉传达高价值信息。
+- ⚡ **AI Analytics (AI 分析)**: 深度分析 Input/Output Token，支持缓存 (Cached) 与推理 (Reasoning) 部分的分离监控。
+- 🔒 **Identity Core (身份核心)**: 完备的身份验证与权限管理，保护你的开发数据资产。
+
+### 🌌 视觉预览
+
+<img src="docs/screenshots/landing.png" width="900" alt="VibeUsage 落地页预览"/>
+
+## 🛠️ 快速开始
+
+### 安装
+
+只需一次初始化，即可变身为“自动驾驶”模式。VibeUsage 会在后台处理所有数据同步，你只需专注开发。
+
+```bash
+npx --yes vibeusage init
+```
+
+说明：交互式终端会显示授权菜单；非交互环境可使用 `--yes` 跳过。
+可选：`--dry-run` 仅预览将发生的变更，不写入任何文件。
+说明：若存在 `~/.code/config.toml`（或 `CODE_HOME`），`init` 会自动配置 Every Code 的 `notify`。配置完成后，数据同步完全自动化，无需后续人工干预。
+说明：若检测到 Gemini CLI home，`init` 会在 `~/.gemini/settings.json` 安装 `SessionEnd` hook，并将 `tools.enableHooks = true` 以确保 hook 生效。这会启用所有 Gemini hooks；如需关闭，可将 `tools.enableHooks = false`（或禁用 `vibeusage-tracker` hook）。
+
+### 同步与状态查看
+
+````bash
+虽然同步是自动完成的，但你仍可以随时手动触发同步或查看状态：
+
+```bash
+# 手动同步最新的本地会话数据 (可选)
+npx --yes vibeusage sync
+
+# 查看当前连接状态
+npx --yes vibeusage status
+````
+
+### 日志来源
+
+- Codex CLI 日志：`~/.codex/sessions/**/rollout-*.jsonl`（可用 `CODEX_HOME` 覆盖）
+- Every Code 日志：`~/.code/sessions/**/rollout-*.jsonl`（可用 `CODE_HOME` 覆盖）
+- Gemini CLI 日志：`~/.gemini/tmp/**/chats/session-*.json`（可用 `GEMINI_HOME` 覆盖）
+
+## 🔧 环境变量
+
+- `VIBESCORE_HTTP_TIMEOUT_MS`：CLI 请求超时（毫秒，默认 `20000`，`0` 表示关闭，范围 `1000..120000`）。
+- `VITE_VIBESCORE_HTTP_TIMEOUT_MS`：Dashboard 请求超时（毫秒，默认 `15000`，`0` 表示关闭，范围 `1000..30000`）。
+- `GEMINI_HOME`：覆盖 Gemini CLI 的 home（默认 `~/.gemini`）。
+
+## 🧰 常见问题
+
+### Streak 显示 0 天但总量正常
+
+- Streak 的口径是“从今天开始连续使用的天数”，如果今天的 total 为 0，streak 就是 0。
+- 如果你确认应该有 streak，请清理本地缓存并重新登录：
+
+```js
+localStorage.removeItem("vibeusage.dashboard.auth.v1");
+Object.keys(localStorage)
+  .filter((k) => k.startsWith("vibeusage.heatmap."))
+  .forEach((k) => localStorage.removeItem(k));
+location.reload();
+```
+
+- 刷新后重新走一遍 landing page 的登录流程。
+- 说明：Dashboard 不使用 `insforge-auth-token`，实际存储在 `vibeusage.dashboard.auth.v1`。
+
+## 🏗️ 系统架构
+
+```mermaid
+graph TD
+    A[Codex CLI] -->|Rollout Logs| B(Tracker CLI)
+    B -->|AI Tokens| C{Core Relay}
+    C --> D[VibeUsage Dashboard]
+    C --> E[AI Analytics Engine]
+```
+
+## 💻 开发者指南
+
+如果你想在本地运行或贡献代码：
+
+### 仪表盘开发
+
+```bash
+# 安装依赖
+cd dashboard
+npm install
+
+# 启动开发服务器
+npm run dev
+```
+
+### 调试字段（Usage 接口）
+
+当请求包含 `debug=1` 时，usage 接口会在响应体中附带 `debug` 对象，方便前端定位慢查询而不依赖响应头。
+
+```ts
+const res = await fetch(
+  `${baseUrl}/functions/vibeusage-usage-summary?from=2025-12-30&to=2025-12-30&debug=1`,
+  {
+    headers: { Authorization: `Bearer ${userJwt}` }
+  }
+);
+const data = await res.json();
+
+if (data.debug) {
+  console.debug('usage debug', {
+    requestId: data.debug.request_id,
+    status: data.debug.status,
+    queryMs: data.debug.query_ms,
+    slowThresholdMs: data.debug.slow_threshold_ms,
+    slowQuery: data.debug.slow_query
+  });
+}
+```
+
+### 整体架构验证
+
+```bash
+# 验证 Copy 注册表
+npm run validate:copy
+
+# 执行烟雾测试
+npm run smoke
+```
+
+## 📜 开源协议
+
+本项目基于 [MIT](LICENSE) 协议开源。
+
+---
+
+<div align="center">
+  <b>System_Ready // 2024 VibeUsage OS</b><br/>
+  <i>"More Tokens. More Vibe."</i>
+</div>

package/bin/tracker.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+const { run } = require('../src/cli');
+const { stripDebugFlag } = require('../src/lib/debug-flags');
+
+const { argv, debug } = stripDebugFlag(process.argv.slice(2));
+if (debug) process.env.VIBEUSAGE_DEBUG = '1';
+
+run(argv).catch((err) => {
+  console.error(err?.stack || String(err));
+  if (debug) {
+    if (typeof err?.status === 'number') {
+      console.error(`Status: ${err.status}`);
+    }
+    if (typeof err?.code === 'string' && err.code.trim()) {
+      console.error(`Code: ${err.code.trim()}`);
+    }
+    const original = err?.originalMessage;
+    if (original && original !== err?.message) {
+      console.error(`Original error: ${original}`);
+    }
+    if (typeof err?.nextActions === 'string' && err.nextActions.trim()) {
+      console.error(`Next actions: ${err.nextActions.trim()}`);
+    }
+  }
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "vibeusage",
+  "version": "0.2.8",
+  "description": "Codex CLI token usage tracker (macOS-first, notify-driven).",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "commonjs",
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "smoke": "node scripts/smoke/insforge-smoke.cjs",
+    "build:insforge": "node scripts/build-insforge-functions.cjs",
+    "build:insforge:check": "node scripts/build-insforge-functions.cjs --check",
+    "dashboard:dev": "npm --prefix dashboard run dev",
+    "dashboard:build": "npm --prefix dashboard run build",
+    "dashboard:preview": "npm --prefix dashboard run preview",
+    "dev:shim": "node scripts/dev-bin-shim.cjs",
+    "validate:copy": "node scripts/validate-copy-registry.cjs",
+    "copy:pull": "node scripts/copy-sync.cjs pull",
+    "copy:push": "node scripts/copy-sync.cjs push",
+    "architecture:canvas": "node scripts/ops/architecture-canvas.cjs",
+    "validate:guardrails": "node scripts/validate-architecture-guardrails.cjs"
+  },
+  "bin": {
+    "tracker": "bin/tracker.js",
+    "vibeusage": "bin/tracker.js",
+    "vibeusage-tracker": "bin/tracker.js",
+    "vibescore-tracker": "bin/tracker.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "esbuild": "0.27.2"
+  },
+  "dependencies": {
+    "@insforge/sdk": "^1.0.4"
+  }
+}

package/src/cli.js

@@ -0,0 +1,64 @@
+const { cmdInit } = require('./commands/init');
+const { cmdSync } = require('./commands/sync');
+const { cmdStatus } = require('./commands/status');
+const { cmdDiagnostics } = require('./commands/diagnostics');
+const { cmdUninstall } = require('./commands/uninstall');
+
+async function run(argv) {
+  const [command, ...rest] = argv;
+
+  if (!command || command === '-h' || command === '--help') {
+    printHelp();
+    return;
+  }
+
+  switch (command) {
+    case 'init':
+      await cmdInit(rest);
+      return;
+    case 'sync':
+      await cmdSync(rest);
+      return;
+    case 'status':
+      await cmdStatus(rest);
+      return;
+    case 'diagnostics':
+      await cmdDiagnostics(rest);
+      return;
+    case 'uninstall':
+      await cmdUninstall(rest);
+      return;
+    default:
+      throw new Error(`Unknown command: ${command}`);
+  }
+}
+
+function printHelp() {
+  // Keep this short; npx users want quick guidance.
+  process.stdout.write(
+    [
+      'vibeusage',
+      '',
+      'Usage:',
+      '  npx vibeusage [--debug] init [--yes] [--dry-run] [--no-open] [--link-code <code>]',
+      '  npx vibeusage [--debug] sync [--auto] [--drain]',
+      '  npx vibeusage [--debug] status',
+      '  npx vibeusage [--debug] diagnostics [--out diagnostics.json]',
+      '  npx vibeusage [--debug] uninstall [--purge]',
+      '',
+      'Notes:',
+      '  - init: consent first, local setup next, browser sign-in last.',
+      '  - --yes skips the consent menu (non-interactive safe).',
+      '  - --dry-run previews changes without writing files.',
+      '  - optional: --link-code <code> skips browser login when provided by Dashboard.',
+      '  - Every Code notify installs when ~/.code/config.toml exists.',
+      '  - auto sync waits for a device token.',
+      '  - optional: VIBEUSAGE_DASHBOARD_URL or --dashboard-url for hosted landing.',
+      '  - sync parses ~/.codex/sessions/**/rollout-*.jsonl and ~/.code/sessions/**/rollout-*.jsonl, then uploads token deltas.',
+      '  - --debug shows original backend errors.',
+      ''
+    ].join('\n')
+  );
+}
+
+module.exports = { run };

package/src/commands/diagnostics.js

@@ -0,0 +1,39 @@
+const path = require('node:path');
+
+const { writeFileAtomic, chmod600IfPossible } = require('../lib/fs');
+const { collectTrackerDiagnostics } = require('../lib/diagnostics');
+
+async function cmdDiagnostics(argv = []) {
+  const opts = parseArgs(argv);
+  const diagnostics = await collectTrackerDiagnostics();
+  const json = JSON.stringify(diagnostics, null, opts.compact ? 0 : 2) + '\n';
+
+  if (opts.out) {
+    const outPath = path.resolve(process.cwd(), opts.out);
+    await writeFileAtomic(outPath, json);
+    await chmod600IfPossible(outPath);
+    process.stderr.write(`Wrote diagnostics to: ${outPath}\n`);
+  }
+
+  process.stdout.write(json);
+}
+
+function parseArgs(argv) {
+  const out = {
+    out: null,
+    compact: false
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--out') out.out = argv[++i] || null;
+    else if (a === '--compact') out.compact = true;
+    else if (a === '--pretty') out.compact = false;
+    else throw new Error(`Unknown option: ${a}`);
+  }
+
+  return out;
+}
+
+module.exports = { cmdDiagnostics };
+