pi-tui-status-beautifier 1.7.0 → 1.7.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +190 -15
- package/extensions/tui-status-beautifier.ts +11 -7
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,31 +1,206 @@
|
|
|
1
1
|
# pi-tui-status-beautifier
|
|
2
2
|
|
|
3
|
-
Minimalist status bar formatter & AI-customizable layout engine for
|
|
3
|
+
> **Minimalist status bar formatter & AI-customizable layout engine for Pi TUI**
|
|
4
|
+
> Normalizes verbose, mismatched extension status badges into clean, coherent typography with zero runtime render-loop disk I/O.
|
|
4
5
|
|
|
5
|
-
|
|
6
|
+
[](https://www.npmjs.com/package/pi-tui-status-beautifier)
|
|
7
|
+
[](LICENSE)
|
|
8
|
+
[](https://github.com/earendil-works/pi-coding-agent)
|
|
9
|
+
[-brightgreen)](extensions/tui-status-beautifier.spec.ts)
|
|
10
|
+
[](tsconfig.json)
|
|
6
11
|
|
|
7
|
-
|
|
12
|
+
**English** | [简体中文](./README_zh.md)
|
|
8
13
|
|
|
14
|
+
```text
|
|
15
|
+
┌─ Native Status Bar (Fragmented & Cluttered) ────────────────────────────────────────────────────────┐
|
|
16
|
+
│ plannotator: 🟢 3 tasks pi-mcp-adapter: [connected] toolflow: active (2/5) anchor: 3 items │
|
|
17
|
+
└─────────────────────────────────────────────────────────────────────────────────────────────────────┘
|
|
18
|
+
│
|
|
19
|
+
▼
|
|
20
|
+
┌─ pi-tui-status-beautifier (Normalized, Coherent & Adaptive) ────────────────────────────────────────┐
|
|
21
|
+
│ plan ❯ ◆ 3 mcp ❯ ● ready toolflow ❯ ⌬ 2/5 anchor ❯ ⌖ 3 chrome ❯ ● connected │
|
|
22
|
+
└─────────────────────────────────────────────────────────────────────────────────────────────────────┘
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Why pi-tui-status-beautifier?
|
|
28
|
+
|
|
29
|
+
As the Pi terminal ecosystem grows, developers routinely install multiple extensions (`plannotator`, `pi-mcp-adapter`, `toolflow`, `pi-anchor`, `pi-control-chrome`, `pi-lingual`). Over time, the footer status bar deteriorates into visual chaos:
|
|
30
|
+
|
|
31
|
+
1. **Inconsistent Syntax & Naming**: Every extension authors status strings independently. Some prefix long package names (`pi-mcp-adapter:`), some wrap counts in brackets (`[2]`), while others dump raw emojis or status sentences. The lack of standard metrics distracts focus during coding flow.
|
|
32
|
+
2. **Narrow Terminal Line Wrapping**: In split-pane layouts (tmux, WezTerm, iTerm2 panes `< 80` columns), long status strings wrap onto multiple lines or tear off the edge of the screen, pushing input prompts up and down.
|
|
33
|
+
3. **Surrogate-Pair & CJK Misalignments**: Emojis, East Asian Wide (CJK) characters, and zero-width joiners (ZWJ) trigger width calculation discrepancies in naive string formatters, leading to flickering and cursor misalignment.
|
|
34
|
+
4. **Render-Loop Disk Latency**: Reading configuration files inside high-frequency TUI animation loops introduces I/O thrashing and terminal sluggishness.
|
|
35
|
+
|
|
36
|
+
`pi-tui-status-beautifier` acts as a non-intrusive normalization layer. It intercepts `ctx.ui.setStatus` calls, sanitizes ANSI and surrogate characters, dynamically maps state signals into uniform badges, and folds idle items when horizontal space tightens.
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## Preset Gallery & Visual Themes
|
|
41
|
+
|
|
42
|
+
Switch styles interactively with `/beautify`:
|
|
43
|
+
|
|
44
|
+
```text
|
|
45
|
+
1. stream (Default Minimalist Stream)
|
|
46
|
+
chrome ❯ ● ready toolflow ❯ ⌬ 2/5 anchor ❯ ⌖ 3 plan ❯ ◆ 1
|
|
47
|
+
|
|
48
|
+
2. powerline (Angled Brackets & Distinct Glyphs)
|
|
49
|
+
chrome ‹◆ ready› toolflow ‹◈ 2/5› anchor ‹⌖ 3› plan ‹◆ 1›
|
|
50
|
+
|
|
51
|
+
3. matrix (Dot-Matrix Framing & Star Accents)
|
|
52
|
+
chrome ⦗✦ ready⦘ toolflow ⦗✧ 2/5⦘ anchor ⦗⌖ 3⦘ plan ⦗✦ 1⦘
|
|
53
|
+
|
|
54
|
+
4. glow (High-Contrast Inverse Pill Badges)
|
|
55
|
+
chrome [ ● ready ] toolflow [ ⌬ 2/5 ] anchor [ ⌖ 3 ] plan [ ◆ 1 ]
|
|
56
|
+
|
|
57
|
+
5. minimal (Fixed 10-Column Aligned Stream)
|
|
58
|
+
chrome ❯ ● ready toolflow ❯ ⌬ 2/5 anchor ❯ ⌖ 3
|
|
59
|
+
|
|
60
|
+
6. custom (AI-Assisted Co-Design)
|
|
61
|
+
Generates bespoke separators, framing glyphs, and status indicators matching your aesthetic.
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## Core Capabilities & Architectural Design
|
|
67
|
+
|
|
68
|
+
### 1. Dual-Scope Formatting Architecture
|
|
69
|
+
When configuring `/beautify`, you choose between two execution scopes:
|
|
70
|
+
* **`status-only` (Default & Recommended)**: Only hooks `ctx.ui.setStatus` badges. Leaves Pi's native Git branch, working directory, context window percentages, token telemetry (`↑1.2k ↓3.4k R8.9k`), and thinking levels (`• high`) 100% native and untouched.
|
|
71
|
+
* **`full-footer` (Integrated Geek Footer)**: Replaces the entire bottom bar with a unified two-line layout:
|
|
72
|
+
* **Line 1**: Folder & Git branch on the left; token metrics, context cache hit rates, model identifier, and reasoning level on the right.
|
|
73
|
+
* **Line 2**: Normalized extension status badges with automatic column budgeting.
|
|
74
|
+
|
|
75
|
+
### 2. Adaptive Folding for Narrow Terminals (< 80 Cols)
|
|
76
|
+
In compact split panes, status items risk overflowing terminal boundaries. `pi-tui-status-beautifier` partitions active extensions into two priority tiers:
|
|
77
|
+
* **High-Priority (Active/Warning/Error)**: Badges displaying `running`, `working`, `starting`, `error`, `failed`, or `pause` are always preserved at full fidelity.
|
|
78
|
+
* **Low-Priority (Idle/Ready/Ok)**: When line width exceeds maximum available columns, idle badges are automatically condensed into a compact indicator:
|
|
79
|
+
```text
|
|
80
|
+
toolflow ❯ ⌬ running (2/5) plan ❯ ▲ error (+3 idle)
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### 3. Dedicated Extension Identity & Micro-Spinners
|
|
84
|
+
The engine strips internal package naming suffixes (`-extension`, `-plugin`, `-adapter`, `-slash-text`) and maps established ecosystem tools to clean semantic identities:
|
|
85
|
+
* `plannotator` ➔ `plan` (accent glyph `◆`)
|
|
86
|
+
* `pi-mcp-adapter` ➔ `mcp` (status dot `●`)
|
|
87
|
+
* `pi-control-chrome` ➔ `chrome` (status dot `●`)
|
|
88
|
+
* `pi-anchor` ➔ `anchor` (anchor glyph `⌖`)
|
|
89
|
+
* `toolflow` ➔ `toolflow` (flow glyph `⌬`)
|
|
90
|
+
* `pi-lingual` ➔ `lingual` (exchange glyph `⇄`)
|
|
91
|
+
* In-progress tasks (`running`, `working`, `...`) automatically trigger a 300ms terminal micro-spinner (`◐`, `◓`, `◑`, `◒`).
|
|
92
|
+
|
|
93
|
+
### 4. Zero-Ceremony AI Co-Design (`/beautify custom`)
|
|
94
|
+
Want a unique terminal aesthetic without manually editing code?
|
|
95
|
+
1. Run `/beautify` and select `custom`.
|
|
96
|
+
2. Enter your desired aesthetic in plain text (e.g. *"Cyberpunk neon dots"*, *"Nordic minimal pastels"*, *"Subtle dashed brackets"*).
|
|
97
|
+
3. The beautifier dispatches a structured prompt recipe to your active Coding Agent.
|
|
98
|
+
4. Your agent presents **3 distinct ASCII visual mockups** via interactive selection and writes the chosen configuration directly to `./.pi/settings.json`.
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## Under-The-Hood Engineering
|
|
103
|
+
|
|
104
|
+
### Unicode UAX #11 & Surrogate-Pair Safety
|
|
105
|
+
Terminal character counting based on `string.length` breaks when encountering emojis, Chinese/Japanese characters, or surrogate pairs. `pi-tui-status-beautifier` implements a standalone `codePointAt(0)` scanner (`src/extensions/tui-status-beautifier.ts`):
|
|
106
|
+
* Accurately measures East Asian Wide (2 visual columns), ASCII (1 column), and zero-width markers (0 columns).
|
|
107
|
+
* Explicitly ignores Zero-Width Joiners (`0x200d`), Emoji Variation Selectors (`0xfe0f`, `0xfe0e`), and combining diacritics (`0x0300..0x036f`).
|
|
108
|
+
* Implements `sliceToVisualWidth` to truncate long identifiers without severing multibyte surrogate pairs.
|
|
109
|
+
|
|
110
|
+
### Zero Render-Loop Disk I/O & Dirty-Checking
|
|
111
|
+
* **Cached Memory Reads**: Configuration is loaded into memory at startup. Normal TUI redraw loops perform **zero synchronous file reads (`fs.readFileSync`)**.
|
|
112
|
+
* **State Dirty-Checking**: Renders are cached per badge (`${key}:${currentStyle}`). If an extension sends an identical status string, formatting is skipped, avoiding redundant string allocations.
|
|
113
|
+
* **Atomic Settings Writes**: Style updates via `/beautify` use atomic file replacement (`writeFileSync(temp)` + `renameSync(temp, target)`), preventing corrupt settings files if the process is terminated mid-write.
|
|
114
|
+
|
|
115
|
+
### Zero-Trace Physical Cleanup (`off`)
|
|
116
|
+
Selecting `off` cleanly restores all original unformatted status strings to `ctx.ui.setStatus`, unhooks the footer, and deletes the `beautifier` block from `settings.json`. It leaves zero orphaned configuration schema behind.
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Configuration Reference
|
|
121
|
+
|
|
122
|
+
Settings reside under `"beautifier"` in `./.pi/settings.json` (project-level) or `~/.pi/agent/settings.json` (global):
|
|
123
|
+
|
|
124
|
+
```json
|
|
125
|
+
{
|
|
126
|
+
"beautifier": {
|
|
127
|
+
"style": "stream",
|
|
128
|
+
"fullFooter": false
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### Custom Style Schema (`style: "custom"`)
|
|
134
|
+
```json
|
|
135
|
+
{
|
|
136
|
+
"beautifier": {
|
|
137
|
+
"style": "custom",
|
|
138
|
+
"fullFooter": false,
|
|
139
|
+
"custom": {
|
|
140
|
+
"prefix": "",
|
|
141
|
+
"suffix": "",
|
|
142
|
+
"separator": " ❯ ",
|
|
143
|
+
"brackets": ["⦗", "⦘"],
|
|
144
|
+
"inverse": false,
|
|
145
|
+
"padName": false,
|
|
146
|
+
"glyphs": {
|
|
147
|
+
"success": "●",
|
|
148
|
+
"warning": "◌",
|
|
149
|
+
"error": "▲",
|
|
150
|
+
"accent": "◆"
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## Installation & Usage
|
|
160
|
+
|
|
161
|
+
### Install as a Pi Extension
|
|
9
162
|
```bash
|
|
163
|
+
# Recommended: Install from npm
|
|
10
164
|
pi install npm:pi-tui-status-beautifier
|
|
165
|
+
|
|
166
|
+
# Or install from GitHub
|
|
167
|
+
pi install git:github.com/3ZEROS12/pi-tui-status-beautifier
|
|
11
168
|
```
|
|
12
169
|
|
|
13
|
-
|
|
170
|
+
### Interactive Command
|
|
171
|
+
Type `/beautify` inside any active Pi session to open the interactive style selector:
|
|
172
|
+
```text
|
|
173
|
+
/beautify
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
### Development & Testing
|
|
177
|
+
```bash
|
|
178
|
+
git clone https://github.com/3ZEROS12/pi-tui-status-beautifier.git
|
|
179
|
+
cd pi-tui-status-beautifier
|
|
180
|
+
npm install
|
|
181
|
+
npm test # 18/18 Vitest unit tests pass
|
|
182
|
+
npm run lint # Zero ESLint warnings
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
## Author's Note
|
|
188
|
+
|
|
189
|
+
The reason I created `pi-tui-status-beautifier` comes from a simple aesthetic frustration in daily terminal pairing: visual noise.
|
|
190
|
+
|
|
191
|
+
As I installed multiple extensions for Pi (`pi-mcp-adapter`, `plannotator`, `toolflow`, `pi-anchor`, `pi-lingual`), the status bar quickly deteriorated into a chaotic billboard. Every extension author used their own punctuation, raw emojis, and arbitrary string widths. In split-pane tmux or compact terminal windows, lines tore, right-side borders wrapped onto new rows, and the screen constantly flickered.
|
|
14
192
|
|
|
15
|
-
|
|
193
|
+
When I looked into existing status bar plugins, many took a sledgehammer approach: completely replacing Pi's native footer via `ctx.ui.setFooter`. In doing so, they wiped out essential platform metrics—token usage, cache read rates, thinking levels, and git branches. Even worse, some plugins read configuration files synchronously inside the animation redraw loop, causing typing sluggishness.
|
|
16
194
|
|
|
17
|
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
- **`off`**: Pass through raw status strings untouched
|
|
195
|
+
I built this beautifier around three strict constraints:
|
|
196
|
+
1. Non-destructive scoping: never hijack host platform telemetry; normalize only the extension status badges;
|
|
197
|
+
2. Zero render-loop disk I/O: cache settings in memory and skip duplicate renders;
|
|
198
|
+
3. Zero-trace revert: turning it off physically deletes the config block (`delete config.beautifier`), leaving zero psychological or schema clutter.
|
|
22
199
|
|
|
23
|
-
|
|
200
|
+
A good status bar should be quiet, balanced, and invisible until you need it.
|
|
24
201
|
|
|
25
|
-
|
|
26
|
-
- **Zero Render-Loop Disk I/O**: Reads `~/.pi/agent/settings.json` once at startup and performs dirty-checked in-memory rendering; atomic temp-file rename (`writeFileSync` + `renameSync`) only when switching styles via `/beautify`.
|
|
27
|
-
- **ReDoS-Safe ANSI Stripping**: Fast-path bypass when no ESC/CSI bytes are present.
|
|
202
|
+
---
|
|
28
203
|
|
|
29
204
|
## License
|
|
30
205
|
|
|
31
|
-
MIT
|
|
206
|
+
MIT © [Jason](https://github.com/3ZEROS12)
|
|
@@ -16,6 +16,8 @@ const COMMON_NAMES: Record<string, string> = {
|
|
|
16
16
|
toolflow: "toolflow",
|
|
17
17
|
anchor: "anchor",
|
|
18
18
|
"pi-anchor": "anchor",
|
|
19
|
+
lingual: "lingual",
|
|
20
|
+
"pi-lingual": "lingual",
|
|
19
21
|
};
|
|
20
22
|
|
|
21
23
|
const SPINNERS = ["◐", "◓", "◑", "◒"] as const;
|
|
@@ -301,13 +303,15 @@ export function beautifyStatus(
|
|
|
301
303
|
? "⌖"
|
|
302
304
|
: name === "toolflow"
|
|
303
305
|
? "⌬"
|
|
304
|
-
:
|
|
305
|
-
? "
|
|
306
|
-
: state === "
|
|
307
|
-
? "
|
|
308
|
-
: state === "
|
|
309
|
-
? "
|
|
310
|
-
: "
|
|
306
|
+
: name === "lingual"
|
|
307
|
+
? "⇄"
|
|
308
|
+
: state === "warning"
|
|
309
|
+
? "◌"
|
|
310
|
+
: state === "error"
|
|
311
|
+
? "▲"
|
|
312
|
+
: state === "accent"
|
|
313
|
+
? "◆"
|
|
314
|
+
: "●";
|
|
311
315
|
|
|
312
316
|
// Dynamic micro-spinner for active in-progress / running states (running, working, starting, waiting)
|
|
313
317
|
if (
|
package/package.json
CHANGED