Add top-level README
Lists every extension, the theme, setup scripts, tests, a quick onboarding section, and a repo layout diagram. Links each extension to its source file. Specifically notes the deferred stream-parsing tests and the reason (mock HTTPS harness not worth it for single-user deployment). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,105 @@
|
||||
# pi-extensions
|
||||
|
||||
Personal collection of extensions, themes, and scripts for
|
||||
[pi](https://github.com/badlogic/pi-mono) — Mario Zechner's CLI coding agent.
|
||||
|
||||
The anchor of the repo is **ai-server**, a multi-file pi extension that lets
|
||||
pi talk to a self-hosted llama.cpp router behind mTLS. Everything else (theme,
|
||||
banner, custom footer, working indicator, session-name generator, etc.) is
|
||||
Warhammer 40k "Dark Mechanicum" flavoring on top of pi's interactive TUI.
|
||||
|
||||
## Installed extensions
|
||||
|
||||
| Extension | What it does |
|
||||
|---|---|
|
||||
| [`ai-server/`](ai-server/) | Remote llama.cpp provider over mTLS. Dynamic model discovery. Admin slash commands (load / unload / ctx / preset / restart / refresh). Custom SSE stream implementation with tool calls, reasoning, cache token reporting. See [ai-server/README.md](ai-server/README.md) for the full setup. |
|
||||
| [`local-llama.ts`](local-llama.ts) | Tiny provider registration for a local llama-server (e.g. `127.0.0.1:8088`). |
|
||||
| [`dark-mechanicus-indicator.ts`](dark-mechanicus-indicator.ts) | Replaces pi's default working-indicator with `⚙ <quote> · <elapsed>`. ⚙ pulses gold-dim → normal → bright → normal (1s cycle); one of 45 Dark-Mechanicum quotes rotates every 10s; elapsed time ticks every second. |
|
||||
| [`mechanicus-footer.ts`](mechanicus-footer.ts) | Replaces pi's default footer. Context shown as `45k/131k (34%)` instead of `34%/131k`. Adds compaction counter (`C2`) and last-turn tok/s. |
|
||||
| [`mechanicus-status-line.ts`](mechanicus-status-line.ts) | Third footer line: `⚙ HERETEK FORGE · ACTIVE` / `SCRAPCODE CIRCUITRY · OPERATIONAL` / etc. Rotates each turn. |
|
||||
| [`mechanicus-banner.ts`](mechanicus-banner.ts) | Custom TUI header — cog-and-skull art (`LEX HERETEK`, `SCRAPCODE TRIUMPHS`, `BLOOD-FORGE ETERNAL`) with text block on the left and ASCII cog on the right. |
|
||||
| [`mechanicus-session-names.ts`](mechanicus-session-names.ts) | Auto-names new sessions with a random `<adjective>-<noun> · <NNN>` (e.g. `Heretek-Blood-Forge · 042`). Mirrors the name into the terminal tab title. |
|
||||
| [`mechanicus-thinking-label.ts`](mechanicus-thinking-label.ts) | Swaps pi's `Thinking...` fold-label for `Cogitating...`. |
|
||||
| [`markdown-body-color.ts`](markdown-body-color.ts) | Monkey-patches pi-tui's `Markdown` + `Editor` components so unstyled paragraph text and editor typing text don't inherit the terminal profile's default foreground (often green). Forces a lavender `inkPurple` body color. |
|
||||
|
||||
## Theme
|
||||
|
||||
| File | Palette |
|
||||
|---|---|
|
||||
| [`themes/dark-mechanicus.json`](themes/dark-mechanicus.json) | Dark purple aubergine background (`#16101e`), AdMech blood-red accents (`#a8232c`), burnished brass borders (`#b8803d`), nurgle-green syntax strings (`#5a6b2e`), cognitor-pink syntax types (`#c75a8a`). All 51 color tokens defined. |
|
||||
|
||||
Activate with `/settings` inside pi (or set `"theme": "dark-mechanicus"` in
|
||||
`~/.pi/agent/settings.json`). Pi hot-reloads on edits to the active theme file.
|
||||
|
||||
## Setup scripts
|
||||
|
||||
| Script | Runs on | Purpose |
|
||||
|---|---|---|
|
||||
| [`scripts/install-client.sh`](scripts/install-client.sh) | New pi client | Bootstraps a client: fetches certs from the Caddy host, rsyncs extensions + themes into `~/.pi/agent/`, verifies the mTLS /health endpoint. |
|
||||
| [`scripts/issue-client-cert.sh`](scripts/issue-client-cert.sh) | Caddy host | Generates a new client identity (key + cert + modern + legacy p12) for a named device. Use for each new machine. |
|
||||
| [`scripts/install-browser-certs.sh`](scripts/install-browser-certs.sh) | New client | Imports client cert + root CA into Brave Flatpak NSS, system NSS, Firefox profiles, and optionally the system trust store. Mostly obsolete since the Caddy switch to Let's Encrypt but still useful for the mTLS client cert side. |
|
||||
|
||||
## Tests
|
||||
|
||||
Twenty-eight tests total, no external dependencies. Runs with Node 22+'s
|
||||
built-in test runner + `--experimental-strip-types`:
|
||||
|
||||
```bash
|
||||
node --experimental-strip-types --test tests/*.test.ts
|
||||
```
|
||||
|
||||
| File | Coverage |
|
||||
|---|---|
|
||||
| `tests/messages.test.ts` | 13 unit tests over `ai-server/messages.ts` — pi Context → OpenAI payload conversion (system prompts, user/assistant/tool-result roles, tool calls, image-only messages). |
|
||||
| `tests/router-utils.test.ts` | 9 unit tests over `ai-server/router-utils.ts` — `extractCtxSize`, `isShardArtefact` (the filter that hides GGUF multi-shard phantoms from the model picker). |
|
||||
| `tests/integration.test.ts` | 6 live-endpoint tests: `/health`, `/models`, model-entry shape, mTLS enforcement, publicly-trusted cert (Let's Encrypt contract), chat completion usage shape including `prompt_tokens_details.cached_tokens`. Auto-skip if the server is unreachable. |
|
||||
|
||||
Stream-parsing edge cases (SSE framing, tool-call splits across chunks,
|
||||
reasoning deltas, abort mid-stream) remain deferred — they need a mock
|
||||
HTTPS server harness, not worth the complexity for a one-user setup.
|
||||
|
||||
## Quick onboarding for another machine
|
||||
|
||||
```bash
|
||||
# 1. Mint a new client identity (on the Caddy host)
|
||||
ssh shahondin1624@192.168.2.2 '~/pi-extensions/scripts/issue-client-cert.sh laptop-alice'
|
||||
|
||||
# 2. On the new pi client
|
||||
git clone https://git.shahondin1624.de/shahondin1624/pi-extensions.git ~/pi-extensions
|
||||
cd ~/pi-extensions
|
||||
scripts/install-client.sh
|
||||
|
||||
# 3. Activate the theme
|
||||
# /settings in pi, pick "dark-mechanicus"
|
||||
```
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
pi-extensions/
|
||||
├── ai-server/ the core mTLS provider (multi-file extension)
|
||||
│ ├── index.ts entry — provider + admin commands
|
||||
│ ├── config.ts URLs, SSH host, cert loading, MODELS[]
|
||||
│ ├── messages.ts Context → OpenAI messages
|
||||
│ ├── stream.ts custom SSE stream, mTLS HTTPS, pi-ai events
|
||||
│ ├── admin.ts router HTTP client + SSH helpers
|
||||
│ ├── router-utils.ts pure helpers (test-friendly)
|
||||
│ └── README.md full mTLS + systemd + Caddy setup notes
|
||||
├── dark-mechanicus-indicator.ts working indicator (cog + quote + timer)
|
||||
├── mechanicus-footer.ts custom footer layout
|
||||
├── mechanicus-status-line.ts rotating flavor status line
|
||||
├── mechanicus-banner.ts TUI header art
|
||||
├── mechanicus-session-names.ts auto-name generator + tab title
|
||||
├── mechanicus-thinking-label.ts "Cogitating..." for folded thinking blocks
|
||||
├── markdown-body-color.ts forces body text color for chat + editor
|
||||
├── local-llama.ts local llama-server provider
|
||||
├── themes/
|
||||
│ └── dark-mechanicus.json 51-token theme
|
||||
├── scripts/ install helpers
|
||||
├── tests/ node:test suites
|
||||
└── README.md this file
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
Personal use. No license declared; the repo is private.
|
||||
Reference in New Issue
Block a user