cxstatusline 0.1.1 → 0.4.0

package/README.md

@@ -37,12 +37,11 @@ Independent project; not an official OpenAI product.
 
 ## Requirements
 
-- **macOS 14 (Sonoma) or newer** on Apple Silicon (`darwin-arm64`) or Intel (`darwin-x64`). Clean-macOS-14 acceptance is unproven and evidenced only by build metadata (`MACOSX_DEPLOYMENT_TARGET=14.0`, `vtool` `minos`, and system-only `otool -L` linkage).
+- **macOS 14 (Sonoma) or newer** (Apple Silicon or Intel).
 - **Node.js 22+**.
-- **Stock Codex CLI install** kept in place (`~/.codex/` and original launcher).
+- **Existing Codex CLI installation** kept in place (`~/.codex/`).
 - **Git**.
-- **Bun 1.4+** is required only for building/linking from a git checkout.
-- **Rust toolchain** (1.95.0+) is required only for `cxstatusline install --compile`.
+- **Rust toolchain** (1.95.0+) is required only if building from source (`--compile`).
 
 ## 🚀 Install
 
@@ -54,7 +53,7 @@ cxstatusline install
 cxstatusline doctor
 ```
 
-`install` downloads the release matching your exact Codex version and CPU, verifies every byte against `manifest.json`, and activates it. Nothing is signed or notarized; see [Security and trust](#security-and-trust).
+`install` downloads the verified prebuilt binary matching your exact Codex version and architecture, verifies checksums against `manifest.json`, and activates it.
 
 Start Codex, accept its cxstatusline hook trust prompt, and open a new session after installation. An already-running process does not switch binaries when installation finishes.
 
@@ -102,22 +101,78 @@ cxstatusline
 The bare command opens the configuration TUI in an interactive terminal. Choose widgets, colors
 and themes, preview, then save explicitly or press Ctrl+S. Settings live at
 `~/.config/cxstatusline/settings.json` (or your XDG config location).
-Custom command/weather widgets and unsupported Claude-only widgets are not included.
+Claude-only widgets without a Codex data source are not included; see the widget inventory in the
+project notes for the full list and reasons.
 
 For scripts, `cxstatusline render` reads a versioned JSON payload on stdin and prints ANSI rows;
 it never opens the TUI.
 
+## Custom widgets
+
+Three widgets show your own content, with the same settings fields as ccstatusline so presets import unchanged:
+
+| Widget | Field | Shows |
+|---|---|---|
+| Custom Text | `customText` | A fixed label such as `[PROD]` |
+| Custom Symbol | `customSymbol` | One glyph or emoji such as `⚡` |
+| Custom Command | `commandPath` | The first line a shell command prints |
+
+### Custom Command execution and caching
+
+Custom Command runs `commandPath` through your shell (`/bin/sh -c`) with Codex's environment, in
+the session's working directory. It receives the Codex status payload as JSON on stdin plus `terminal_width`.
+Only the first non-empty line is shown; stderr is discarded. Set `preserveColors` (key `p`) to keep
+the command's own colour codes; other escape sequences and control characters are always removed. Configured
+background colours apply in both render modes and survive resets within the command output. `maxWidth`
+(key `w`) truncates with an ellipsis. The TUI preview never runs commands. Imported presets list their
+commands before you confirm.
+
+#### Synchronous execution (default)
+
+When `refreshMs` is unset (or `0`), commands run synchronously on **every footer redraw** (up to five
+times a second while Codex streams).
+
+Codex kills the whole statusline renderer after one second and keeps the previous frame, so
+cxstatusline caps each synchronous command at **300 ms by default, 600 ms maximum** (`timeout`, editor key
+`t`), and all commands on a render share a 600 ms budget. Over budget shows `[Budget]`; a slow
+command shows `[Timeout]`, a failing one `[Exit: N]` or `[Cmd not found]`. Commands terminated by
+external signals before the deadline report `[Signal: <name>]` rather than `[Timeout]`. Keep synchronous
+commands cheap and local: `git status -s | wc -l` and `date +%H:%M` are good fits; network calls are not.
+
+#### Background caching (`refreshMs`)
+
+For commands that take longer or should not run on every redraw, configure `refreshMs` (key `f`).
+
+- **Background refresh:** When `refreshMs` is set, rendering reads the latest result from disk and never
+  blocks the statusline or consumes renderer timeout budget. When an entry is due for an update,
+  cxstatusline spawns a detached background process to refresh it; the refresh outlives the render.
+- **Cold start:** On the very first render before the initial background run completes, the widget shows
+  `[Loading]`.
+- **Failures and timeouts:** A failing background command caches its exit code or error token; if a
+  background refresh stays outstanding or fails beyond 60 seconds, the widget settles on `[Error]` and
+  keeps showing `[Error]` across subsequent renders until a refresh succeeds.
+- **Cache location:** Cached documents live under `~/.cache/cxstatusline/commands/` (or
+  `$XDG_CACHE_HOME/cxstatusline/commands/`). Deleting this cache directory at any time is completely
+  safe; entries are re-created automatically.
+- **Eviction:** Cache entries and temporary files expire and are automatically evicted after 7 days.
+- **Session sharing constraint:** The cache key is derived from `(command, cwd)`, so every Codex
+  session running in the same working directory shares one cache entry and one payload (the payload
+  written by whichever session triggered the refresh). `refreshMs` is intended for commands whose
+  output does not depend on specific session payload details.
+- **Pipeline processes:** As with synchronous mode, `shell: true` terminates `/bin/sh` on timeout,
+  so child processes spawned inside a shell pipeline can outlive the cap. Avoid long-running pipelines.
+
 ## Update
 
 ```sh
-codex update
-# or
 cxstatusline update
 ```
 
-`codex update` (or `cxstatusline update`) runs Codex's upstream updater, then downloads the matching prebuilt; never compiles.
+`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.
 
-If no verified prebuilt release exists for the new version, cxstatusline fails closed: the working pair is left in place and the command says so. The SessionStart hook retries daily according to update policy.
+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.
 
 ## Revert
 
@@ -127,43 +182,35 @@ cxstatusline revert
 
 `cxstatusline revert` restores the stock launcher, removes CX-owned executables, generations, and the hook, and keeps settings and source. Generations are kept until revert; close Codex sessions first.
 
-## How it works
-
-**Renderer and settings:** The statusline is powered by a Node CLI renderer that receives session metadata from Codex, formats ANSI rows according to your `settings.json`, and writes the footer.
-
-**The additive Rust patch:** Because the Codex CLI does not yet provide an external statusline hook ([openai/codex#17827](https://github.com/openai/codex/issues/17827)), cxstatusline applies a minimal additive patch to `codex-tui` and builds synchronized binaries (`codex` and companion `codex-code-mode-host`). The patch invokes the local renderer without altering Codex's networking or command evaluation.
-
-**Generations and atomic activation:** Each verified pair installs into an immutable generation directory under `~/.local/libexec/cxstatusline/generations/<id>/`. An atomic rename switches the `~/.local/libexec/cxstatusline/current` symlink. The wrapper in `~/.local/bin/codex` resolves `current` once before execution, ensuring running sessions and their companion host stay locked to the same generation. Previous generations accumulate until explicit `cxstatusline revert`.
-
-**SessionStart hook and update policy:** A hook registered in Codex's `hooks.json` checks for upstream version drift on session start. When drift is detected, a detached child process downloads the matching prebuilt release without interrupting your active terminal session.
-
+## 🔍 How it works
+ 
+Codex CLI does not yet provide a native statusline extension hook ([openai/codex#17827](https://github.com/openai/codex/issues/17827)). `cxstatusline` bridges this with a lightweight additive Rust patch that captures session telemetry (model, context tokens, Git branch, rate limits) and invokes a local Node/TypeScript ANSI renderer.
+ 
+Updates use an immutable **generation-based layout** (`~/.local/libexec/cxstatusline/generations/`) with atomic symlink swaps, ensuring your active terminal sessions are never interrupted.
+ 
+👉 For a full architectural breakdown of how Codex is patched with Rust, check out the **[Architecture & Technical Deep Dive (wiki.md)](wiki.md)**.
+ 
 ## Supported versions
-
-cxstatusline matches exact stable releases. Supported versions in `patches/manifest.json`:
-- **0.152.1**
+ 
+cxstatusline matches exact stable releases. Supported versions:
+- **0.154.0**
+- **0.153.4**
 - **0.153.0**
-- **0.153.4** (candidate)
-
+- **0.152.1**
+ 
 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.
-
+ 
 ## 🩺 Troubleshooting
-
+ 
 - **No footer:** Run `cxstatusline doctor`, verify `which codex` points to `~/.local/bin/codex`, check your `PATH`, accept the hook prompt in Codex, and start a fresh session.
 - **Unsupported version:** Wait for an explicitly supported patch. `--force` does not bypass version compatibility. Keep a working stock Codex installation.
 - **Failed build:** Inspect `~/.local/state/cxstatusline/patch.log`, fix the prerequisite, then run `cxstatusline patch --force`. Redact personal paths, session identifiers, and secrets before sharing logs.
 - **Missing companion / interrupted install:** Run `cxstatusline doctor`. Use `cxstatusline revert` to return to stock before reinstalling if unhealthy. Do not manually replace only one binary.
-
-## Security and trust
-
-- **Unsigned and unnotarized:** cxstatusline binaries are not signed or notarized by Apple; macOS Gatekeeper warnings are expected. Do not disable Gatekeeper globally; clear the quarantine attribute for these two files only, or build from source with `install --compile`.
-- **Integrity vs. identity:** Checksums and manifests prove integrity relative to the GitHub release, not publisher identity.
-- **Archive contents:** Each prebuilt release archive contains exactly five files: `codex`, `codex-code-mode-host`, upstream `LICENSE` (Apache-2.0), upstream `NOTICE`, and `THIRD_PARTY_NOTICES.md` (combining cxstatusline notices and generated Rust dependency notices). No extra directories, files, or telemetry.
-- **Security policy:** See [SECURITY.md](SECURITY.md) for full trust boundaries, file layout, and vulnerability reporting.
-
-## Contributing and license
-
-See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and [CHANGELOG.md](CHANGELOG.md).
-
-Inspired by [ccstatusline](https://github.com/sirmalloc/ccstatusline) for Claude Code. Its renderer and configuration UI are adapted here for Codex. Thanks to its creators and contributors!
-
-cxstatusline is [MIT licensed](LICENSE). [NOTICE](NOTICE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) preserve upstream attribution. The build includes dependency license texts in `dist/THIRD_PARTY_LICENSES.txt`. OpenAI Codex remains separately licensed under Apache-2.0.
+ 
+## 🙏 Acknowledgments
+ 
+Huge shout-out to **[ccstatusline](https://github.com/sirmalloc/ccstatusline)** by [@sirmalloc](https://github.com/sirmalloc)! The interactive configurator TUI, widget architecture, Powerline themes, and overall statusline UX in `cxstatusline` are directly adapted and inspired by `ccstatusline`'s fantastic work for Claude Code.
+ 
+## License
+ 
+cxstatusline is [MIT licensed](LICENSE). See [SECURITY.md](SECURITY.md) for security boundaries and reporting. [NOTICE](NOTICE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) preserve upstream attribution. OpenAI Codex remains separately licensed under Apache-2.0.