@seanxdo/superview 0.1.13

package/README.md

@@ -0,0 +1,193 @@
+# SuperView
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+## Quick Start
+
+```bash
+npx @seanxdo/superview
+```
+
+Or install globally:
+
+```bash
+npm install -g @seanxdo/superview
+superview
+```
+
+Then open **http://0.0.0.0:5174** and scan your agent logs.
+
+SuperView is a local-first flight recorder for coding agents. It ingests session logs from Codex, Claude Code, and OpenCode, reconstructs every task journey, and surfaces hidden agent work — context snapshots, tool calls, cost, errors, and project telemetry — in a single dashboard.
+
+## Preview
+
+<table>
+  <tr>
+    <td><img src="docs/assets/02.png" width="100%" alt="SuperView screenshot" /></td>
+    <td><img src="docs/assets/03.png" width="100%" alt="SuperView screenshot" /></td>
+    <td><img src="docs/assets/04.png" width="100%" alt="SuperView screenshot" /></td>
+  </tr>
+  <tr>
+    <td><img src="docs/assets/05.png" width="100%" alt="SuperView screenshot" /></td>
+    <td><img src="docs/assets/06.png" width="100%" alt="SuperView screenshot" /></td>
+    <td><img src="docs/assets/07.png" width="100%" alt="SuperView screenshot" /></td>
+  </tr>
+</table>
+
+## Features
+
+### Session Recap
+
+A collapsible black-box readout panel with five sections:
+
+- **01 Readout** — Sessions, estimated cost, total tokens, tool calls, errors, most-used model, busiest day, and priciest session.
+- **02 Rhythm** — Daily activity calendar heatmap, hour×weekday clock heatmap, and daily token usage chart.
+- **03 Efficiency** — Cache hit rate, error rate, tokens per session, and cost per session with animated gauges.
+- **04 Spend by Model** — Per-model cost breakdown with editable token pricing.
+- **05 Tool Usage** — Horizontal bar chart of tool call frequency with error indicators.
+
+### Context Replay
+
+A snapshot-by-snapshot walkthrough of the agent's context window:
+
+- Numbered step rail showing phase, title, and +added/-dropped content per step.
+- Auto-play mode (cycles snapshots every 2.8s).
+- Context blocks grouped by state: carried forward, newly added, changed, dropped.
+- Warning strip for stale context, contradictions, and missing files.
+- **Factory Strip** — A full-width belt view of all snapshots with active blocks and transitions.
+
+### Token Timeline
+
+A vertical bar chart of token usage per journey, segmented by input/output/cached/reasoning. Click any bar to jump to that journey. Summary bar with conversation count, total tokens, and per-type breakdown.
+
+### Share Card
+
+One-click summary generation for any task journey — hero stat, skills used, verdict (cleared/failed/in-progress), token sparkline, and copy-as-Markdown support.
+
+### Event Tape
+
+A horizontal mini-timeline on every journey row showing categorized events (user, assistant, tool, thinking, error) with tooltip details on hover.
+
+### Cost Estimation
+
+Built-in pricing table for Claude and GPT models (June 2026 rates). All rates are editable in-place. Costs are computed from raw token usage with cache read/write multipliers. Supports per-model cost aggregation.
+
+### Multi-Provider Support
+
+| Provider | Source | Default Path |
+|----------|--------|--------------|
+| Codex CLI | Session JSONL files | `~/.codex/sessions/**/*.jsonl` |
+| Claude Code | Project JSONL files | `~/.claude/projects/**/*.jsonl` |
+| OpenCode | Exported session files | Manual export |
+
+### Theme & Language
+
+Four themes: Bright Command Center (default), Dark Command Center, Forest Lab, Plasma Violet. Full bilingual support: English and Simplified Chinese. Preferences persist across sessions.
+
+## Development
+
+```bash
+pnpm install
+pnpm dev          # Start API + Vite dev server
+```
+
+Open the app:
+
+```
+http://127.0.0.1:5173/
+```
+
+The API server runs at:
+
+```
+http://127.0.0.1:5174/
+```
+
+### CLI Ingest
+
+```bash
+pnpm ingest /path/to/.codex
+```
+
+### API Ingest
+
+```bash
+curl -X POST http://127.0.0.1:5174/api/ingest \
+  -H 'Content-Type: application/json' \
+  -d '{"sources":[{"provider":"codex"}]}'
+```
+
+Claude Code:
+
+```bash
+curl -X POST http://127.0.0.1:5174/api/ingest \
+  -H 'Content-Type: application/json' \
+  -d '{"sources":[{"provider":"claude-code","root":"/path/to/.claude"}]}'
+```
+
+OpenCode:
+
+```bash
+curl -X POST http://127.0.0.1:5174/api/ingest \
+  -H 'Content-Type: application/json' \
+  -d '{"sources":[{"provider":"opencode","path":"/path/to/opencode-export.json"}]}'
+```
+
+Poll job status:
+
+```bash
+curl http://127.0.0.1:5174/api/ingest/jobs/<jobId>
+```
+
+### Scripts
+
+```bash
+pnpm dev          # Start API and Vite client
+pnpm dev:server   # Start the Express API only
+pnpm dev:client   # Start the Vite client only
+pnpm start        # Start production server (single port, serves API + UI)
+pnpm build        # Typecheck and build the UI
+pnpm typecheck    # Run TypeScript checks
+pnpm test         # Run Vitest tests
+pnpm test:e2e     # Run Playwright tests
+```
+
+## API Reference
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/health` | GET | Health check |
+| `/api/ingest` | POST | Start ingest job |
+| `/api/ingest/jobs/:id` | GET | Poll ingest progress |
+| `/api/projects` | GET | List all projects |
+| `/api/projects/:id/timeline` | GET | Get project timeline |
+| `/api/projects/:id/token-usage/daily` | GET | Daily token usage |
+| `/api/task-journeys/:id` | GET | Journey detail |
+| `/api/task-journeys/:id/context-replay` | GET | Context replay data |
+| `/api/events/:id/evidence` | GET | Event evidence |
+| `/api/runs/:id` | GET | Run replay |
+| `/api/reset` | POST | Reset database |
+
+## Architecture
+
+```text
+ui/            React + Vite dashboard
+runtime-node/  Express API, ingest service, worker process, log adapters
+core/          Parser, normalizer, redactor, cost engine, timeline, context replay
+storage/       SQLite database layer and local data paths
+```
+
+The ingest path is intentionally split from the API. The API creates an ingest job and returns immediately. A worker process scans and parses log files, then writes normalized data into SQLite. This keeps the dashboard responsive during large historical scans. Ingest uses single-flight behavior — if one is already active, subsequent requests return the existing job.
+
+## Environment Variables
+
+```bash
+SUPERVIEW_DATA_DIR     # Data directory (default: ./.superview)
+SUPERVIEW_CODEX_HOME   # Codex log root (default: ~/.codex)
+SUPERVIEW_CLAUDE_HOME  # Claude Code log root (default: ~/.claude)
+SUPERVIEW_PORT         # Production server port (default: 5174)
+```
+
+## Privacy
+
+SuperView is local-first. No accounts, no cloud sync, no remote backend. Raw agent logs stay on your machine. Normalized records are stored in a local SQLite database. Evidence views expose only redacted payloads with source provenance (path, line, timestamp, hash) — enough for debugging, not raw dumps.

package/README.zh-CN.md

@@ -0,0 +1,193 @@
+# SuperView
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+## 快速开始
+
+```bash
+npx @seanxdo/superview
+```
+
+或全局安装：
+
+```bash
+npm install -g @seanxdo/superview
+superview
+```
+
+然后打开 **http://0.0.0.0:5174**，扫描你的 agent 日志即可。
+
+SuperView 是一个本地优先的 coding agent 飞行记录器。它会读取 Codex、Claude Code 和 OpenCode 的 session 日志，重建每一轮任务旅程，并将隐藏的 agent 工作——上下文快照、工具调用、成本、错误和项目遥测——呈现在一个统一的仪表盘中。
+
+## 界面预览
+
+<table>
+  <tr>
+    <td><img src="docs/assets/02.png" width="100%" alt="SuperView 截图" /></td>
+    <td><img src="docs/assets/03.png" width="100%" alt="SuperView 截图" /></td>
+    <td><img src="docs/assets/04.png" width="100%" alt="SuperView 截图" /></td>
+  </tr>
+  <tr>
+    <td><img src="docs/assets/05.png" width="100%" alt="SuperView 截图" /></td>
+    <td><img src="docs/assets/06.png" width="100%" alt="SuperView 截图" /></td>
+    <td><img src="docs/assets/07.png" width="100%" alt="SuperView 截图" /></td>
+  </tr>
+</table>
+
+## 功能
+
+### 会话概览
+
+可折叠的黑匣子面板，包含五个模块：
+
+- **01 总览** — 会话数、预估成本、Token 总量、工具调用次数、错误数、最常用模型、最忙一天和最贵项目。
+- **02 节奏** — 每日活动日历热力图、小时×星期时钟热力图、每日 Token 用量图表。
+- **03 效率** — 缓存命中率、错误率、每次会话 Token 数、每次会话成本，带动画仪表条。
+- **04 模型成本** — 按模型分组的成本明细表，支持自定义 Token 定价。
+- **05 工具用量** — 工具调用频率的横向柱状图，标注错误次数。
+
+### 上下文回放
+
+按快照逐步回溯 agent 的上下文窗口：
+
+- 编号步骤栏，显示每步的阶段、标题和 +新增/-丢弃 内容。
+- 自动播放模式（每 2.8 秒切换快照）。
+- 上下文块按状态分组：延续、新增、变更、丢弃。
+- 警告条：过期上下文、矛盾信息、缺失文件。
+- **工厂流水线** — 全宽皮带视图，展示所有快照节点及其活跃上下文块的流转。
+
+### Token 时间线
+
+每次旅程的 Token 用量纵向柱状图，按输入/输出/缓存/推理分段。点击任意柱子跳转到对应旅程。顶部汇总条显示会话总数、Token 总量和分类明细。
+
+### 分享卡片
+
+一键生成任务旅程摘要——关键统计、使用技能、判定结果（完成/失败/进行中）、Token 火花图和 Markdown 格式复制。
+
+### 事件条
+
+每条旅程行上的水平迷你时间线，以颜色区分事件类型（用户、agent、工具、思考、错误），悬停显示详情。
+
+### 成本估算
+
+内置 Claude 和 GPT 模型定价表（2026 年 6 月费率）。所有费率可实时编辑。根据原始 Token 用量计算成本，含缓存读写系数。支持按模型聚合成本。
+
+### 多提供商支持
+
+| 提供商 | 数据来源 | 默认路径 |
+|--------|---------|---------|
+| Codex CLI | Session JSONL 文件 | `~/.codex/sessions/**/*.jsonl` |
+| Claude Code | Project JSONL 文件 | `~/.claude/projects/**/*.jsonl` |
+| OpenCode | 导出 session 文件 | 手动导出 |
+
+### 主题与语言
+
+四种主题：明亮指挥中心（默认）、暗色指挥中心、森林实验室、等离子紫。完整双语支持：英文和简体中文。偏好设置跨会话持久保存。
+
+## 本地开发
+
+```bash
+pnpm install
+pnpm dev          # 启动 API + Vite 开发服务器
+```
+
+打开应用：
+
+```
+http://127.0.0.1:5173/
+```
+
+API 服务地址：
+
+```
+http://127.0.0.1:5174/
+```
+
+### CLI 导入
+
+```bash
+pnpm ingest /path/to/.codex
+```
+
+### API 导入
+
+```bash
+curl -X POST http://127.0.0.1:5174/api/ingest \
+  -H 'Content-Type: application/json' \
+  -d '{"sources":[{"provider":"codex"}]}'
+```
+
+Claude Code：
+
+```bash
+curl -X POST http://127.0.0.1:5174/api/ingest \
+  -H 'Content-Type: application/json' \
+  -d '{"sources":[{"provider":"claude-code","root":"/path/to/.claude"}]}'
+```
+
+OpenCode：
+
+```bash
+curl -X POST http://127.0.0.1:5174/api/ingest \
+  -H 'Content-Type: application/json' \
+  -d '{"sources":[{"provider":"opencode","path":"/path/to/opencode-export.json"}]}'
+```
+
+查询任务状态：
+
+```bash
+curl http://127.0.0.1:5174/api/ingest/jobs/<jobId>
+```
+
+### 常用脚本
+
+```bash
+pnpm dev          # 同时启动 API 和 Vite 客户端
+pnpm dev:server   # 只启动 Express API
+pnpm dev:client   # 只启动 Vite 客户端
+pnpm start        # 启动生产服务器（单端口，同时提供 API + UI）
+pnpm build        # 类型检查并构建 UI
+pnpm typecheck    # 运行 TypeScript 检查
+pnpm test         # 运行 Vitest 测试
+pnpm test:e2e     # 运行 Playwright 测试
+```
+
+## API Reference
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/api/health` | GET | 健康检查 |
+| `/api/ingest` | POST | 启动导入任务 |
+| `/api/ingest/jobs/:id` | GET | 查询导入进度 |
+| `/api/projects` | GET | 列出所有项目 |
+| `/api/projects/:id/timeline` | GET | 获取项目时间线 |
+| `/api/projects/:id/token-usage/daily` | GET | 每日 Token 用量 |
+| `/api/task-journeys/:id` | GET | 任务旅程详情 |
+| `/api/task-journeys/:id/context-replay` | GET | 上下文回放数据 |
+| `/api/events/:id/evidence` | GET | 事件证据 |
+| `/api/runs/:id` | GET | 运行回放 |
+| `/api/reset` | POST | 重置数据库 |
+
+## 架构
+
+```text
+ui/            React + Vite 仪表盘
+runtime-node/  Express API、导入服务、工作进程、日志适配器
+core/          解析器、规范化器、脱敏器、成本引擎、时间线、上下文回放
+storage/       SQLite 数据库层和本地数据路径
+```
+
+导入路径与 API 路径分离。API 创建导入任务后立即返回，工作进程独立扫描和解析日志文件，将标准化数据写入 SQLite。即使扫描大量历史会话，仪表盘也能保持响应。导入服务采用单飞模式——若已有任务在运行，后续请求返回现有任务而非启动新的全量扫描。
+
+## 环境变量
+
+```bash
+SUPERVIEW_DATA_DIR     # 数据目录（默认：./.superview）
+SUPERVIEW_CODEX_HOME   # Codex 日志根目录（默认：~/.codex）
+SUPERVIEW_CLAUDE_HOME  # Claude Code 日志根目录（默认：~/.claude）
+SUPERVIEW_PORT         # 生产服务器端口（默认：5174）
+```
+
+## 隐私
+
+SuperView 完全本地运行。无需账号、云同步或远程后端。原始 agent 日志始终留在你的机器上。标准化记录存储在本地 SQLite 数据库中。证据视图仅暴露脱敏 payload 及来源信息（路径、行号、时间戳、哈希），足以用于调试，但不会泄露原始内容。