cxstatusline 0.8.0 → 0.9.1

package/README.md

@@ -2,7 +2,7 @@
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/banner-dark.png">
-  <img alt="cxstatusline" src="docs/banner-light.png" width="720">
+  <img alt="cxstatusline - Customizable statusline & powerline status bar for OpenAI Codex CLI" src="docs/banner-light.png" width="720">
 </picture>
 
 # cxstatusline
@@ -13,26 +13,51 @@
 
 [![CI](https://github.com/adrijshikhar/cxstatusline/actions/workflows/ci.yml/badge.svg)](https://github.com/adrijshikhar/cxstatusline/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/cxstatusline.svg)](https://www.npmjs.com/package/cxstatusline)
+[![Website](https://img.shields.io/badge/website-cxstatusline.adrijshikhar.dev-blue)](https://cxstatusline.adrijshikhar.dev)
+[![Playground](https://img.shields.io/badge/playground-online-purple)](https://cxstatusline.adrijshikhar.dev/#playground)
+[![Discussions](https://img.shields.io/github/discussions/adrijshikhar/cxstatusline)](https://github.com/adrijshikhar/cxstatusline/discussions)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 [![Node.js 22+](https://img.shields.io/badge/node-%E2%89%A522-green)](https://nodejs.org/)
 
-![cxstatusline configurator: adding a widget and changing colors with live sample-data previews](docs/demo.gif)
+![cxstatusline interactive terminal configuration TUI - customize widgets, colors, and powerline themes](docs/demo.gif)
 
 </div>
 
+## 📑 Table of Contents
+
+- [✨ Features](#-features)
+- [🌐 Interactive Web Playground](#-interactive-web-playground)
+- [📋 Requirements](#requirements)
+- [🚀 Install](#-install)
+- [🎛️ Configure](#️-configure)
+- [🧩 Widgets Catalog](#widgets)
+- [🔄 Update & Revert](#update)
+- [🔍 How it Works](#-how-it-works)
+- [🏷️ Supported Versions](#supported-versions)
+- [🩺 Troubleshooting](#-troubleshooting)
+- [🙏 Acknowledgments](#-acknowledgments)
+
 ## ✨ Features
 
-A configurable, one-to-three-row statusline for [OpenAI Codex CLI](https://github.com/openai/codex),
-with an interactive configuration TUI, colors, Powerline themes and preset import/export.
-See model, context, Git, session duration, usage percentages and reset times without leaving Codex.
-Available data depends on your session and account.
+**cxstatusline** is a configurable, one-to-three-row statusline & status bar for the [OpenAI Codex CLI](https://github.com/openai/codex) (bringing the rich statusbar experience of [ccstatusline](https://github.com/sirmalloc/ccstatusline) for Anthropic Claude Code to OpenAI Codex).
+
+- **⚡ Live Codex Telemetry**: Monitor active model, reasoning effort, context token window usage (`k/200k`), session duration, and rate limit reset countdowns in real time.
+- **🌿 Git Status & Branch**: Always see current branch and unstaged/staged change counters (`+42, -10`) right in your Codex prompt.
+- **🎨 Powerline Themes & ANSI Colors**: Choose from built-in Powerline separators (arrows, angled, curved, flame), 16/256/TrueColor palettes, or design custom rows.
+- **🖥️ Interactive Terminal TUI**: Configure your layout visually inside your terminal (`cxstatusline`) or in the web playground.
+- **🔄 ccstatusline Compatibility**: Preset syntax and widget IDs match ccstatusline, making transition from Claude Code seamless.
 
 Independent project; not an official OpenAI product.
 
+## 🌐 Interactive Web Playground
+
+Try out themes, arrange widgets, and preview your custom OpenAI Codex statusline directly in your browser without installing anything:
+👉 **[cxstatusline.adrijshikhar.dev](https://cxstatusline.adrijshikhar.dev)**
+
 <details>
 <summary>See the footer inside Codex</summary>
 
-![cxstatusline footer inside Codex](docs/statusline.png)
+![cxstatusline footer status bar inside OpenAI Codex CLI terminal session](docs/statusline.png)
 
 </details>
 
@@ -55,7 +80,9 @@ cxstatusline doctor
 ```
 
 `cxstatusline install` downloads the verified prebuilt binary matching your Codex version, verifies checksums against `manifest.json`, and activates it.
-- **Interactive selection**: Running `cxstatusline install` in a terminal prompts you to choose from available supported versions (defaulting to your detected or latest version).
+- **Interactive selection**: Running `cxstatusline install` opens a keyboard-driven version picker. Use ↑/↓ and Enter to select, or Escape/Ctrl+C to cancel. Prebuilt availability is shown per version; source-only choices require confirmation (unless you already passed `--compile`).
+- **Update choices**: `cxstatusline update` uses the same keyboard controls to choose the latest supported prebuilt, a supported source build, or cancellation. It does not update upstream Codex first.
+- **Live progress**: Ink renders download progress in terminals while completed stages remain in the transcript. Source builds report their phases; redirected output retains plain milestone logs.
 - **Target a specific version**: `cxstatusline install --codex-version <version>` (e.g. `cxstatusline install --codex-version 0.154.0`).
 - **Non-interactive / CI**: Pass `-y` or `--yes` to accept the default without prompting.
 
@@ -126,11 +153,15 @@ the **[Usage guide](docs/usage.md)**.
 cxstatusline update
 ```
 
-`cxstatusline update` runs a pre-flight check: if upstream Codex has a new version but prebuilts have not yet been published, it warns and stops before touching your active installation.
+`cxstatusline update` downloads and verifies the latest published prebuilt supported by your cxstatusline package, then activates the complete patched Codex pair. It does not run Codex's self-updater or modify your original Codex installation. Open a new Codex session afterward.
+
+The same Codex version is checked for rebuilt patch assets; a newer installed version is never downgraded. If discovery or verification fails, the active pair stays in place. Update the cxstatusline npm package to pick up support for newer Codex versions.
 
 Options:
-- `cxstatusline update --compile`: updates upstream Codex and compiles the statusline from source for the new version.
-- `cxstatusline update --force`: updates upstream Codex to stock immediately, even if prebuilt binaries are not yet published.
+- `cxstatusline update --compile`: builds the latest locally supported Codex patch from source instead.
+- `--force`, `-y`, and `--yes` remain accepted for compatibility; updates already run without a prompt and always verify the pair.
+
+Session-start updates also leave a newer patched pair in place when the original Codex installation is older, including under the `every` policy.
 
 ## Revert
 
@@ -174,7 +205,26 @@ cxstatusline install --codex-version 0.154.0
 ```
 </details>
 
+Rust patch versions are independent of Codex and cxstatusline package versions. Each supported Codex version belongs to exactly one patch version:
+
+| Rust patch | Tested Codex versions |
+| --- | --- |
+| v1 | 0.152.1, 0.153.0, 0.153.1, 0.153.4, 0.154.0, 0.155.0, 0.155.1 |
+| v2 | 0.156.0, 0.156.1 |
+
+Codex 0.153.1 is validated on macOS ARM64; its prebuilt release is pending. Compatibility entries do not imply that a prebuilt has already been published.
+
+`patches/manifest.json` records that ownership with `patchVersion` on each compatibility entry. Its `version: 2` is the manifest format, not the Rust patch version. Entries can describe inclusive ranges, but we currently list only the exact tested versions. Version-specific patch files remain separate because upstream source layouts differ.
+
+Add newly tested Codex versions to the existing patch version while it continues to work. When a newer Codex needs a changed Rust integration, introduce the next patch version for that Codex version and future compatible releases. Do not backport it or reassign older Codex versions. Overlapping entries are rejected.
+
+New builds record the patch version in release and installation metadata; `cxstatusline doctor` displays it. Older releases remain readable and report `unknown (legacy)` rather than guessing. New prebuilt manifests use schema 2, so installing them requires a cxstatusline package that supports this format. Release tags remain `codex-v<version>`.
+
+Rebuilding an existing Codex tag replaces its complete release asset set. The workflow verifies the new build, downloads and verifies every old asset, and saves a 90-day workflow artifact before mutation. The Git tag remains; the release may be briefly unavailable while the replacement is uploaded and verified. If automatic recovery fails, download the matching `release-backup-<tag>-<run-id>` artifact and restore it with `bun scripts/prebuilt.ts restore --tag codex-v0.156.1 --codex-version 0.156.1 --backup-dir ./release-backup --repo adrijshikhar/cxstatusline`.
+
 If your Codex version is not listed, cxstatusline fails closed: it will neither download an unverified prebuilt nor attempt source compilation. New versions require a tested patch file, an entry in `patches/manifest.json`, and a release workflow run.
+
+The daily upstream watcher audits every stable release in the newest Codex major.minor series and only the `.0` baseline of older series, at or above the support floor. For example, while 0.156.x is newest, 0.156.0 and 0.156.1 are required alongside 0.155.0; 0.155.1 is not a backfill requirement. Existing published assets and tested compatibility mappings are retained. It updates one `Codex release coverage gaps` issue and uploads a machine-readable report. A separate watchdog fails if no successful scheduled watcher run has completed in the last 36 hours. Enable repository **Settings → Notifications → Actions** and select failed workflow runs (or enable email notifications for Actions) to receive these failures. The watchdog runs inside GitHub Actions, so a GitHub-wide scheduling outage cannot be detected from within GitHub.
  
 ## 🩺 Troubleshooting
  
@@ -193,5 +243,15 @@ cxstatusline is [MIT licensed](LICENSE). See [SECURITY.md](SECURITY.md) for secu
 
 ---
 
-📦 **npm:** [https://www.npmjs.com/package/cxstatusline](https://www.npmjs.com/package/cxstatusline)
+- 🌐 **Web Playground:** [cxstatusline.adrijshikhar.dev](https://cxstatusline.adrijshikhar.dev)
+- 💬 **Discussions & Ideas:** [github.com/adrijshikhar/cxstatusline/discussions](https://github.com/adrijshikhar/cxstatusline/discussions)
+- 📦 **npm Package:** [npmjs.com/package/cxstatusline](https://www.npmjs.com/package/cxstatusline)
+
+### Prebuilt build machine
 
+All Codex prebuilt jobs run on the owner's M5 Pro (`192.168.1.65`, Actions labels
+`self-hosted`, `macOS`, `ARM64`, `m5-pro`). macOS builds natively; Linux builds in
+Docker on that same M5. Keep the laptop and runner active until the workflow finishes.
+An offline M5 leaves jobs queued; there is no hosted fallback. Platform builds run
+sequentially, preserving 3 native Rust compiler jobs and 8 inside Docker. Dispatch from a ref containing this policy;
+older release tags may still contain the removed hosted-runner option.