rinco-pi-hud 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rinco-pi-hud contributors
+
+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/NOTICE

@@ -0,0 +1,18 @@
+This package is a personal derivative of pi-sakura-cyberdeck by beautifulrem.
+Original project: https://github.com/beautifulrem/pi-sakura-cyberdeck
+License: MIT.
+
+This package contains a dynamic HUD footer for Pi, adapted from the Footer
+portion of pi-zentui by Luka: https://github.com/lmilojevicc/pi-zentui
+License: MIT.
+
+Session, model, activity, MCP, configuration-count, and Codex subscription
+status capabilities are adapted from pi-shannon-statusline by RealAlexandreAI:
+https://github.com/RealAlexandreAI/pi-shannon-statusline
+License: MIT. The integrated presentation has been rewritten for the HUD footer;
+Shannon's HUD, Matrix animation, independent Footer, and Monokai palette are
+not included.
+
+The Codex usage client included under extensions/hud/telemetry/codex-usage
+derives from pi-codex-usage by narumiruna and is MIT licensed. Its full license
+text is kept at extensions/hud/telemetry/codex-usage/LICENSE.

package/README.md

@@ -0,0 +1,204 @@
+<div align="center">
+
+# Rinco Pi HUD
+
+**A dynamic HUD footer for [Pi](https://github.com/earendil-works/pi).**
+
+[![Pi package](https://img.shields.io/badge/Pi-package-F2A7C6?style=flat-square)](https://github.com/earendil-works/pi) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![Tests](https://img.shields.io/badge/tests-Vitest-6E9F18?style=flat-square&logo=vitest&logoColor=white)](https://vitest.dev/) [![License](https://img.shields.io/badge/license-MIT-C7B8F5?style=flat-square)](LICENSE)
+
+[Features](#features) · [Installation](#installation) · [Usage](#usage) · [Customization](#customization) · [Development](#development)
+
+[简体中文](docs/README.zh-CN.md)
+
+</div>
+
+Rinco Pi HUD provides a rich, real-time status footer for Pi TUI sessions. It displays project state, Git metrics, runtime versions, session activity, model usage, token costs, and more — all in a configurable three-line or single-line layout. Pi loads the TypeScript extension directly, so no build step is required (`tsconfig.json` sets `noEmit: true` and is used only for `npm run typecheck`).
+
+## Features
+
+- **Project state** — Working directory, Git branch, commit, tag, status, diff metrics, and runtime versions.
+- **Session activity** — Model, provider, context usage, tokens, cache, session cost, turn count, and thinking level.
+- **Tool and agent activity** — Native tool completion counts, running tools, active agent runs, skills, and MCP server status.
+- **Model quota** — Automatic Codex weekly quota or Token Switch balance display by model provider.
+- **Git awareness** — Branches, detached HEAD, tags, ahead/behind, stash, merge/rebase conflicts, and dirty state.
+- **Runtime detection** — Node, Python, Go, Rust, Java, and 60+ other runtimes with package version parsing.
+- **Configurable layout** — Three-line categorized layout by default, or fully customizable single-line templates.
+- **Extension statuses** — Reads third-party extension statuses and places them by configurable position and color mode.
+- **Safe fallback** — Graceful timeout and error handling; no stale data after session shutdown.
+
+## Installation
+
+### Install from npm (recommended)
+
+```bash
+pi install npm:rinco-pi-hud
+```
+
+The published package is available on [npm](https://www.npmjs.com/package/rinco-pi-hud).
+
+### Install from GitHub
+
+```bash
+pi install git:github.com/Rinisnotarobot/rinco-pi-hud
+```
+
+### Install from a local checkout
+
+```bash
+git clone https://github.com/Rinisnotarobot/rinco-pi-hud.git
+cd rinco-pi-hud
+pi install "$PWD"
+```
+
+> [!IMPORTANT]
+> Pi extensions run with your user permissions. Review the source before installing any third-party extension.
+
+## Usage
+
+Restart Pi after installation, or run:
+
+```text
+/reload
+```
+
+The HUD footer is enabled by default. Run `/zentui` to open the interactive settings UI.
+
+### Common commands
+
+```text
+/zentui statusline enable
+/zentui statusline disable
+/zentui statusline toggle
+/zentui format clear
+/zentui format "$model · $context · $cost · $git_branch( $git_commit) · $session_duration"
+/codex-status
+/usage-refresh
+```
+
+> [!NOTE]
+> For the best result, use a Truecolor terminal and a Nerd Font. The footer uses Unicode glyphs that render best with proper font support.
+
+## Project contents
+
+| Path | Purpose |
+| --- | --- |
+| [`extensions/hud/index.ts`](extensions/hud/index.ts) | Extension lifecycle and side-effect orchestration |
+| [`extensions/hud/config/`](extensions/hud/config/config.ts) | Configuration model, normalization, and persistence |
+| [`extensions/hud/footer/`](extensions/hud/footer/index.ts) | Footer rendering, categorized layout, and template parsing |
+| [`extensions/hud/segments/`](extensions/hud/segments/) | State collectors: Git, runtime, MCP, skills, projects, etc. |
+| [`extensions/hud/telemetry/`](extensions/hud/telemetry/format.ts) | Usage formatting, token switch, and Codex subscription client |
+| [`extensions/hud/session/`](extensions/hud/session/) | Session lifecycle, context, and live context overlay |
+| [`extensions/hud/state/`](extensions/hud/state/) | Aggregated state, telemetry, and project refresh |
+| [`extensions/hud/commands/`](extensions/hud/commands/settings.ts) | `/zentui` command and interactive TUI settings |
+| [`extensions/hud/ui/`](extensions/hud/ui/) | Icons and terminal style utilities |
+| [`docs/footer.md`](docs/footer.md) | Complete footer configuration reference |
+| [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) | Local development, testing guidance, and pull request checklist |
+| [`tests/`](tests/) | Vitest test suite (34+ tests across 6 files) |
+
+## Customization
+
+### Layout
+
+The default three-line layout groups project, session, and usage information. Set `footerFormat` to a template string for a single-line layout:
+
+```text
+/zentui format "$cwd( $git_branch)$fill($context)( $tokens)( $cost)"
+```
+
+Template variables use `$name` or `${name}` syntax. See the [footer reference](docs/footer.md) for the complete variable list.
+
+### Segments
+
+Enable or disable individual status segments via `/zentui`:
+
+```text
+/zentui statusline enable
+/zentui statusline disable
+/zentui statusline toggle
+```
+
+### Extension statuses
+
+Third-party extensions publish statuses that the HUD footer can display. Configure placement (`left`, `middle`, `right`, `off`) and color mode (`zentui`, `original`) for each extension status key.
+
+## Development
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) 22.19 or later
+- [Pi](https://github.com/earendil-works/pi)
+
+Install development dependencies:
+
+```bash
+npm install
+```
+
+### Available commands
+
+<!-- AUTO-GENERATED: package-scripts:start -->
+<!-- Source: package.json#scripts. Do not edit manually. -->
+
+| Command | Description |
+| --- | --- |
+| `npm test` | Run the complete Vitest suite once. |
+| `npm run test:watch` | Run Vitest in watch mode and retest when files change. |
+| `npm run typecheck` | Run TypeScript type checking with `tsc --noEmit`. |
+| `npm run pack:check` | Inspect the publishable package with `npm pack --dry-run` without publishing it. |
+
+<!-- AUTO-GENERATED: package-scripts:end -->
+
+Run the test suite:
+
+```bash
+npm test
+```
+
+Check types:
+
+```bash
+npm run typecheck
+```
+
+Verify tests and package contents:
+
+```bash
+npm test
+npm run typecheck
+npm run pack:check
+```
+
+Vitest covers footer layout, telemetry, codex usage, token switch, config counts, and MCP status parsing. Pi loads the TypeScript source directly, so this project has no separate build command.
+
+## Troubleshooting
+
+### The footer does not appear
+
+1. Confirm that Pi is running in TUI mode rather than headless, JSON, or print mode.
+2. Run `/reload` or restart Pi.
+3. Run `pi list` to confirm that the package is installed.
+
+### The footer layout looks wrong
+
+The footer auto-detects terminal width and truncates content. In narrow terminals, some segments may be clipped. Adjust the layout by setting a custom `footerFormat` template, or disable low-priority segments in `/zentui`.
+
+### Colors look incorrect
+
+Make sure your terminal supports Truecolor. The footer emits `38;2;r;g;b` ANSI sequences.
+
+### Unicode icons are missing or misaligned
+
+Unicode and Nerd Font glyphs vary between terminals and fonts. Install a Nerd Font, or switch to ASCII icon mode via `/zentui`.
+
+## Third-party licenses
+
+This package incorporates work from the following open-source projects:
+
+- **pi-zentui** by Luka — MIT licensed. The Footer portion was adapted for this package.  
+  Source: https://github.com/lmilojevicc/pi-zentui
+- **pi-shannon-statusline** by RealAlexandreAI — MIT licensed. Session, model, activity, MCP, configuration-count, and Codex subscription capabilities were adapted.  
+  Source: https://github.com/RealAlexandreAI/pi-shannon-statusline
+- **pi-codex-usage** by narumiruna — MIT licensed. The Codex usage client under `extensions/hud/telemetry/codex-usage/` derives from this project.  
+  Source: https://github.com/narumiruna/pi-codex-usage
+
+See [NOTICE](NOTICE) for details.

package/docs/CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contributing
+
+Thank you for helping improve Rinco Pi HUD. This guide describes the local development, testing, and submission workflow.
+
+## Development environment
+
+Before you begin, install:
+
+- Node.js 22.19 or later
+- npm
+- Pi, for validating the HUD footer in a real TUI
+
+Clone the project and install its dependencies:
+
+```bash
+git clone https://github.com/Rinisnotarobot/rinco-pi-hud.git
+cd rinco-pi-hud
+npm install
+```
+
+Pi loads the TypeScript extension directly, so this project has no separate build step. Accordingly, `tsconfig.json` sets `noEmit: true` — it is used only for type checking (`npm run typecheck`), never for compiling output.
+
+## Available commands
+
+<!-- AUTO-GENERATED: package-scripts:start -->
+<!-- Source: package.json#scripts. Do not edit manually. -->
+
+| Command | Description |
+| --- | --- |
+| `npm test` | Run the complete Vitest suite once. |
+| `npm run test:watch` | Run Vitest in watch mode and retest when files change. |
+| `npm run typecheck` | Run TypeScript type checking with `tsc --noEmit`. |
+| `npm run pack:check` | Inspect the publishable package with `npm pack --dry-run` without publishing it. |
+
+<!-- AUTO-GENERATED: package-scripts:end -->
+
+## Testing
+
+Before submitting a change, run:
+
+```bash
+npm test
+npm run typecheck
+npm run pack:check
+```
+
+Tests live in `tests/`:
+
+- `zentui-status.test.ts` — Config counts, MCP status parsing, and extension status helpers.
+- `codex-usage.test.ts` — Codex payload normalization and model-specific quota formatting.
+- `footer-layout.test.ts` — Categorized three-line layout and narrow-width budget.
+- `model-switch-statusline.test.ts` — Model switch statusline integration.
+- `model-usage-refresh.test.ts` — Model usage refresh integration.
+- `token-switch-usage.test.ts` — Token Switch balance formatting.
+
+When adding tests:
+
+1. Use Vitest's `describe`, `it`, and `expect` APIs.
+2. Name files `*.test.ts` and place them in `tests/`.
+3. Prefer user-observable behavior over internal implementation details.
+4. Use Vitest fake timers for timer-dependent behavior and restore them after each test.
+5. Keep tests isolated from one another and independent of a real terminal.
+
+In addition to automated tests, validate HUD behavior in a real Pi TUI across different terminal widths, model switches, and project types.
+
+## Code style
+
+The project currently has no configured linter, formatter, or pre-commit hook. Follow the existing conventions:
+
+- Use TypeScript ESM and explicit types.
+- Use two-space indentation, double quotes, and semicolons.
+- Keep extension lifecycle handling clear and release timers and UI state during `session_shutdown`.
+- Do not edit content enclosed by `AUTO-GENERATED` markers manually; regenerate it from the source identified in the marker.
+
+Do not add ignore rules, skip tests, or weaken types merely to bypass a check.
+
+## Architecture notes
+
+The HUD extension is organized into functional modules under `extensions/hud/`:
+
+- **`index.ts`** — Lifecycle and side-effect orchestration.
+- **`config/`** — Configuration model, normalization, and persistence.
+- **`footer/`** — Footer rendering, categorized layout, and template parsing.
+- **`segments/`** — State collectors: Git, runtime, MCP, skills, projects, etc.
+- **`telemetry/`** — Usage formatting, token switch, and Codex subscription client.
+- **`session/`** — Session lifecycle, context, and live context overlay.
+- **`state/`** — Aggregated state, telemetry, and project refresh.
+- **`commands/`** — `/zentui` command and interactive TUI settings.
+- **`ui/`** — Icons and terminal style utilities.
+
+Key conventions:
+
+- Keep event listeners and side-effects in `index.ts`; do not read files or spawn processes in `render()`.
+- Async results check session generation before applying.
+- Timers should be cleaned up on shutdown and `unref()` where possible.
+- State collectors return explicit `ok` / `error` / `not found` semantics.
+- Use `visibleWidth()` and `truncateToWidth()` for terminal width calculations.
+
+## Pull request checklist
+
+Before opening a pull request, confirm that:
+
+- [ ] The change has a focused scope and contains no unrelated files.
+- [ ] New behavior or bug fixes include appropriate tests.
+- [ ] `npm test` passes.
+- [ ] `npm run typecheck` passes.
+- [ ] `npm run pack:check` passes and the package contains the expected files.
+- [ ] Affected HUD behavior was verified in a real Pi TUI.
+- [ ] Related documentation was synchronized from its source of truth.
+- [ ] No `node_modules/`, `.tgz` archives, or sensitive data were committed.

package/docs/README.zh-CN.md

@@ -0,0 +1,204 @@
+<div align="center">
+
+# Rinco Pi HUD
+
+**为 [Pi](https://github.com/earendil-works/pi) 打造的动态 HUD 脚注。**
+
+[![Pi package](https://img.shields.io/badge/Pi-package-F2A7C6?style=flat-square)](https://github.com/earendil-works/pi) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![Tests](https://img.shields.io/badge/tests-Vitest-6E9F18?style=flat-square&logo=vitest&logoColor=white)](https://vitest.dev/) [![License](https://img.shields.io/badge/license-MIT-C7B8F5?style=flat-square)](../LICENSE)
+
+[功能](#功能) · [安装](#安装) · [使用](#使用) · [定制](#定制) · [开发](#开发)
+
+[English](../README.md)
+
+</div>
+
+Rinco Pi HUD 为 Pi TUI 会话提供丰富的实时状态脚注，可显示项目状态、Git 指标、运行时版本、会话活动、模型用量、Token 费用等信息，支持可配置的三行或单行布局。Pi 可直接加载 TypeScript 扩展，无需构建步骤（`tsconfig.json` 设置了 `noEmit: true`，仅用于 `npm run typecheck` 类型检查）。
+
+## 功能
+
+- **Project state**：当前目录、Git 分支、Commit、Tag、工作区状态、差异指标和运行时版本。
+- **Session activity**：模型、Provider、Context 用量、Token、缓存、会话费用、轮次和 Thinking 等级。
+- **Tool and agent activity**：Native Tool 完成次数、正在运行的 Tool、活跃 Agent 数、Skill 和 MCP Server 状态。
+- **Model quota**：根据当前模型自动切换 Codex 周限额或 Token Switch 余额。
+- **Git awareness**：分支、Detached HEAD、Tag、Ahead/Behind、Stash、合并冲突和脏状态。
+- **Runtime detection**：支持 Node、Python、Go、Rust、Java 等 60+ 运行时，并解析项目清单版本。
+- **Configurable layout**：默认三行分类布局，或完全自定义的单行模板。
+- **Extension statuses**：读取第三方扩展发布的状态，按配置的位置和颜色模式显示。
+- **Safe fallback**：超时和错误处理优雅，会话关闭后不留过期数据。
+
+## 安装
+
+### 从 npm 安装（推荐）
+
+```bash
+pi install npm:rinco-pi-hud
+```
+
+该包已发布至 [npm](https://www.npmjs.com/package/rinco-pi-hud)。
+
+### 从 GitHub 安装
+
+```bash
+pi install git:github.com/Rinisnotarobot/rinco-pi-hud
+```
+
+### 从本地目录安装
+
+```bash
+git clone https://github.com/Rinisnotarobot/rinco-pi-hud.git
+cd rinco-pi-hud
+pi install "$PWD"
+```
+
+> [!IMPORTANT]
+> Pi 扩展以当前用户权限运行。安装任何第三方扩展前，请先审查其源码。
+
+## 使用
+
+安装后重启 Pi，或执行：
+
+```text
+/reload
+```
+
+HUD 脚注默认启用。运行 `/zentui` 打开交互式设置。
+
+### 常用命令
+
+```text
+/zentui statusline enable
+/zentui statusline disable
+/zentui statusline toggle
+/zentui format clear
+/zentui format "$model · $context · $cost · $git_branch( $git_commit) · $session_duration"
+/codex-status
+/usage-refresh
+```
+
+> [!NOTE]
+> 最佳显示效果需要支持 Truecolor 的终端和 Nerd Font。脚注使用 Unicode 符号，需要合适的字体支持。
+
+## 包含内容
+
+| 路径 | 说明 |
+| --- | --- |
+| [`extensions/hud/index.ts`](../extensions/hud/index.ts) | 扩展生命周期与副作用编排 |
+| [`extensions/hud/config/`](../extensions/hud/config/config.ts) | 配置模型、归一化与持久化 |
+| [`extensions/hud/footer/`](../extensions/hud/footer/index.ts) | 脚注渲染、分类布局与模板解析 |
+| [`extensions/hud/segments/`](../extensions/hud/segments/) | 状态采集器：Git、运行时、MCP、Skill、项目等 |
+| [`extensions/hud/telemetry/`](../extensions/hud/telemetry/format.ts) | 用量格式化、Token Switch 与 Codex 订阅客户端 |
+| [`extensions/hud/session/`](../extensions/hud/session/) | 会话生命周期、上下文与实时上下文覆盖 |
+| [`extensions/hud/state/`](../extensions/hud/state/) | 聚合状态、遥测与项目刷新 |
+| [`extensions/hud/commands/`](../extensions/hud/commands/settings.ts) | `/zentui` 命令与交互式 TUI 设置 |
+| [`extensions/hud/ui/`](../extensions/hud/ui/) | 图标与终端样式工具 |
+| [`docs/footer.md`](footer.md) | 完整脚注配置参考 |
+| [`docs/CONTRIBUTING.md`](CONTRIBUTING.md) | 本地开发、测试规范和 PR 检查清单 |
+| [`tests/`](../tests/) | Vitest 测试套件（34+ 测试用例，6 个文件） |
+
+## 定制
+
+### 布局
+
+默认三行布局将项目、会话和用量信息分组显示。设置 `footerFormat` 模板字符串可切换为单行布局：
+
+```text
+/zentui format "$cwd( $git_branch)$fill($context)( $tokens)( $cost)"
+```
+
+模板变量使用 `$name` 或 `${name}` 语法。完整变量列表见[脚注参考](footer.md)。
+
+### 状态段
+
+通过 `/zentui` 启用或禁用单个状态段：
+
+```text
+/zentui statusline enable
+/zentui statusline disable
+/zentui statusline toggle
+```
+
+### 扩展状态
+
+第三方扩展发布的状态可由 HUD 脚注显示。可为每个扩展状态键配置位置（`left`、`middle`、`right`、`off`）和颜色模式（`zentui`、`original`）。
+
+## 开发
+
+### 环境要求
+
+- [Node.js](https://nodejs.org/) 22.19 或更高版本
+- [Pi](https://github.com/earendil-works/pi)
+
+安装开发依赖：
+
+```bash
+npm install
+```
+
+### 可用命令
+
+<!-- AUTO-GENERATED: package-scripts:start -->
+<!-- Source: package.json#scripts. Do not edit manually. -->
+
+| 命令 | 说明 |
+| --- | --- |
+| `npm test` | 使用 Vitest 运行一次完整测试套件。 |
+| `npm run test:watch` | 以监听模式运行 Vitest，并在文件变化后重新测试。 |
+| `npm run typecheck` | 使用 `tsc --noEmit` 运行 TypeScript 类型检查。 |
+| `npm run pack:check` | 使用 `npm pack --dry-run` 检查发布包内容，不生成正式发布。 |
+
+<!-- AUTO-GENERATED: package-scripts:end -->
+
+运行测试：
+
+```bash
+npm test
+```
+
+类型检查：
+
+```bash
+npm run typecheck
+```
+
+验证测试与发布内容：
+
+```bash
+npm test
+npm run typecheck
+npm run pack:check
+```
+
+本项目使用 Vitest 测试脚注布局、遥测、Codex 用量、Token Switch、配置统计和 MCP 状态解析。Pi 运行时会直接加载 TypeScript 源码，因此没有单独的构建命令。
+
+## 常见问题
+
+### 脚注没有显示
+
+1. 确认当前运行在 Pi TUI 模式，而不是 Headless、JSON 或 Print 模式。
+2. 执行 `/reload` 或重启 Pi。
+3. 使用 `pi list` 确认包已安装。
+
+### 脚注布局异常
+
+脚注会自动检测终端宽度并截断内容。在窄终端中，部分状态段可能被裁剪。可通过设置自定义 `footerFormat` 模板调整布局，或在 `/zentui` 中关闭低优先级段。
+
+### 颜色显示异常
+
+确认终端已启用 Truecolor。脚注使用 `38;2;r;g;b` ANSI 序列。
+
+### Unicode 图标缺失或错位
+
+Unicode 和 Nerd Font 符号的显示效果因终端和字体而异。建议安装 Nerd Font，或在 `/zentui` 中切换到 ASCII 图标模式。
+
+## 第三方许可证
+
+本包包含以下开源项目的衍生作品：
+
+- **pi-zentui**（Luka）— MIT 许可。脚注部分经改编后用于本包。  
+  源码：https://github.com/lmilojevicc/pi-zentui
+- **pi-shannon-statusline**（RealAlexandreAI）— MIT 许可。会话、模型、活动、MCP、配置统计和 Codex 订阅功能改编自该项目。  
+  源码：https://github.com/RealAlexandreAI/pi-shannon-statusline
+- **pi-codex-usage**（narumiruna）— MIT 许可。`extensions/hud/telemetry/codex-usage/` 下的 Codex 用量客户端衍生自该项目。  
+  源码：https://github.com/narumiruna/pi-codex-usage
+
+详见 [NOTICE](../NOTICE)。