@opencode-cockpit/status 0.3.0 → 0.3.1

package/README.md

@@ -40,6 +40,19 @@ leaves out:
 Everything else is one line of config away — including the things the host shows, if you want them
 in both places.
 
+## A whole line by name
+
+Composing fourteen segments is a design exercise; most people want a good line. A preset is
+built-ins only — nothing to install, nothing to write:
+
+```jsonc
+{ "statusline": { "preset": "default" } }
+```
+
+`minimal` · `default` · `detailed` · `sidebar`. Anything you write beside one wins, so it is a
+starting point and not a mode. See [`examples/`](./examples) for the modules to reach for when a
+preset is not enough.
+
 ## Configuration
 
 `~/.config/opencode-cockpit/config.json` for every project, `<project>/.cockpit.json` for one, and
@@ -140,6 +153,38 @@ rather than reporting `$0.00`; `context` hides itself where nobody declared a wi
 inventing a denominator; `diagnostics` is silent while everything is healthy. That rule matters
 behind a proxy — see [Proxies](#proxies-litellm-and-friends).
 
+## Replacing OpenCode's own sidebar blocks
+
+Each block of OpenCode's sidebar is an internal plugin, and `tui.json` can switch one off:
+
+```jsonc
+// ~/.config/opencode/tui.json
+{
+  "plugin": ["@opencode-cockpit/status"],
+  "plugin_enabled": { "internal:sidebar-context": false }
+}
+```
+
+That removes the host's own `Context / tokens / % used / spent` block, leaving the space to a
+`sidebar` line of your own — the honest way to avoid reading the same figure twice. The same works
+for `internal:sidebar-files`, `-todo`, `-lsp`, `-mcp`, `-footer`, and the home screen's
+`internal:home-footer` and `internal:home-tips`.
+
+## What you can draw
+
+A segment returns styled runs of text, so the design space is finite and worth seeing all at once.
+`examples/gallery.ts` draws every technique in one column — solid, gradient, fine and split bars, a
+bar painted in background colour, steps, a sparkline, rules, dots, chips, dividers, emphasis, every
+tone, and one segment returning several rows:
+
+```sh
+bunx @opencode-cockpit/status preview --module examples/gallery.ts --state working
+```
+
+It is a terminal, not a browser — no DOM, no images, no borders. What there is: truecolor
+foreground and background, bold, dim, and alignment. See
+[What you can draw](https://codestz.github.io/opencode-cockpit/status/drawing/).
+
 ## Your own segments, in TypeScript
 
 The declarative config covers the usual line and a shell command covers anything with a CLI. Neither
@@ -188,8 +233,10 @@ Returning `undefined` hides the segment. A segment that throws loses only its ow
 A module that will not load raises a toast naming the file, rather than silently dropping segments.
 
 **Worked examples** live in [`examples/`](./examples): `bottom.ts` is a complete line for a window
-with no sidebar; `sidebar.ts` is a quiet column beside OpenCode's own Context block. Both are loaded
-and asserted by the test suite, so neither can rot.
+with no sidebar; `sidebar.ts` is a quiet column beside OpenCode's own Context block;
+`sidebar-full.ts` replaces that block; `sidebar-budget.ts` is that column drawn as a table, with a
+budget from a proxy and the branch's diff; `gallery.ts` draws every technique at once. All of them
+are loaded and asserted by the test suite, so none of them can rot.
 
 ## Your Claude Code statusline
 

package/dist/cli/ansi.js

@@ -0,0 +1,46 @@
+/**
+ * Drawing a statusline to a real terminal, outside OpenCode.
+ *
+ * The TUI paints runs through OpenTUI against the running theme; here the same runs are written as
+ * ANSI so a design can be looked at without restarting anything. The colours approximate a dark
+ * theme — close enough to judge a design, never the authority on one.
+ */
+
+const TONE_RGB = {
+  text: [232, 237, 242],
+  muted: [138, 148, 160],
+  accent: [57, 211, 83],
+  success: [57, 211, 83],
+  warning: [232, 185, 35],
+  error: [248, 81, 73],
+  info: [110, 168, 254],
+  background: [11, 13, 16],
+  panel: [38, 43, 51],
+  border: [62, 70, 80]
+};
+function hexRgb(hex) {
+  const value = hex.replace("#", "");
+  const full = value.length === 3 ? [...value].map(c => c + c).join("") : value;
+  if (full.length !== 6) return undefined;
+  const n = Number.parseInt(full, 16);
+  return Number.isNaN(n) ? undefined : [n >> 16 & 255, n >> 8 & 255, n & 255];
+}
+const ESC = String.fromCharCode(27);
+const fg = ([r, g, b]) => `${ESC}[38;2;${r};${g};${b}m`;
+const bg = ([r, g, b]) => `${ESC}[48;2;${r};${g};${b}m`;
+const RESET = `${ESC}[0m`;
+
+/** Dim is rendered as a darker colour rather than the SGR attribute, which terminals disagree on. */
+function darken([r, g, b]) {
+  return [Math.round(r * 0.62), Math.round(g * 0.62), Math.round(b * 0.62)];
+}
+export function paint(run) {
+  const own = run.color ? hexRgb(run.color) : undefined;
+  let colour = own ?? TONE_RGB[run.tone ?? "text"];
+  if (run.dim) colour = darken(colour);
+  const back = run.bg ? hexRgb(run.bg) : run.bgTone ? TONE_RGB[run.bgTone] : undefined;
+  return [back ? bg(back) : "", fg(colour), run.bold ? `${ESC}[1m` : "", run.text, RESET].join("");
+}
+export function paintRuns(runs) {
+  return runs.map(paint).join("");
+}

package/dist/cli/preview.js

@@ -0,0 +1,136 @@
+/**
+ * Draw your statusline in this terminal, against sample sessions, without restarting OpenCode.
+ *
+ *   bunx @opencode-cockpit/status preview
+ *   bunx @opencode-cockpit/status preview --config ~/.config/opencode-cockpit/config.json
+ *   bunx @opencode-cockpit/status preview --state full --width 60
+ *
+ * Why this exists: a statusline is a visual thing, and editing TypeScript, restarting OpenCode and
+ * squinting is a loop measured in minutes. One sidebar took about twenty restarts to design, and
+ * three of the mistakes were glyph choices that read differently in a terminal than they do in a
+ * sentence. Nothing here can tell you a design is good; it can tell you what it looks like.
+ */
+
+import { watch } from "node:fs";
+import { asSegmentConfig, loadStatusConfig, resolveLines } from "../core/config.js";
+import { loadCustomSegments, resolveModulePath } from "../core/custom.js";
+import { FIXTURES } from "../core/fixtures.js";
+import { fit, fitColumn } from "../core/render.js";
+import { buildSegments, segmentWidth } from "../core/segments.js";
+import { paintRuns } from "./ansi.js";
+const args = process.argv.slice(2).filter(arg => arg !== "preview");
+const flag = name => {
+  const at = args.indexOf(`--${name}`);
+  return at === -1 ? undefined : args[at + 1];
+};
+const has = name => args.includes(`--${name}`);
+if (has("help")) {
+  console.log(`
+  preview — draw your statusline here, against sample sessions
+
+    --config <path>   a config file (default: your global + project config)
+    --module <path>   load a module, in addition to any the config names
+    --state <name>    ${Object.keys(FIXTURES).join(" | ")} (default: every one)
+    --width <n>       columns available to the line (default: the surface's own)
+    --debug           mark segments that drew nothing, so silence and typos look different
+    --watch           redraw whenever the config or a module changes
+`);
+  process.exit(0);
+}
+const directory = process.cwd();
+const configPath = flag("config");
+const config = configPath ? (await Bun.file(configPath).json()).statusline ?? {} : loadStatusConfig(directory);
+const modules = [...(config.modules ?? []), ...(flag("module") ? [flag("module")] : [])];
+let custom = new Map();
+if (modules.length > 0) {
+  const loaded = await loadCustomSegments(modules, directory);
+  custom = loaded.segments;
+  for (const error of loaded.errors) console.error(`  module failed: ${error}`);
+}
+const lines = resolveLines(config);
+const states = flag("state") ? [flag("state")] : Object.keys(FIXTURES);
+const debug = has("debug") || config.debug === true;
+
+/** The room each surface actually has in OpenCode, so a preview is not wider than the real thing. */
+const roomFor = (line, terminal) => line.surface === "sidebar" ? 34 : terminal - line.paddingLeft - line.paddingRight;
+const width = Number(flag("width") ?? 0) || 0;
+const dim = text => `${String.fromCharCode(27)}[38;2;110;120;132m${text}${String.fromCharCode(27)}[0m`;
+async function draw() {
+  const watched = [];
+  for (const state of states) {
+    const fixture = FIXTURES[state];
+    if (!fixture) {
+      console.error(`  unknown state "${state}" — try ${Object.keys(FIXTURES).join(", ")}`);
+      process.exit(1);
+    }
+    console.log(`\n${dim(`── ${state} — ${fixture.about}`)}`);
+    for (const line of lines) {
+      const room = width || roomFor(line, process.stdout.columns || 120);
+      const ctx = {
+        ...fixture.ctx,
+        width: room
+      };
+      const built = buildSegments(ctx, line.segments.map(asSegmentConfig), {
+        custom,
+        icons: line.icons,
+        debug
+      });
+      const fitted = line.stack === "vertical" ? fitColumn(built, room, line.maxRows) : fit(built, room, line.separator);
+      if (fitted.segments.length === 0) {
+        console.log(`  ${dim(`(${line.surface}: nothing to draw)`)}`);
+        continue;
+      }
+      console.log(`  ${dim(`${line.surface}, ${room} cols`)}`);
+      if (line.stack === "vertical") {
+        for (const segment of fitted.segments) console.log(`  ${paintRuns(segment.runs)}`);
+      } else {
+        const parts = fitted.segments.map(segment => paintRuns(segment.runs));
+        console.log(`  ${parts.join(dim(line.separator))}`);
+      }
+      /** Rows a real sidebar would have dropped in silence. */
+      if (fitted.dropped > 0) {
+        const over = line.stack === "vertical" ? `maxRows is ${line.maxRows}` : `${room} columns`;
+        console.log(`  ${dim(`↳ ${fitted.dropped} dropped — ${over}`)}`);
+      }
+      const widest = Math.max(0, ...fitted.segments.map(segmentWidth));
+      if (line.stack === "vertical" && widest > room) {
+        console.log(`  ${dim(`↳ widest row is ${widest} cols, the column has ${room}`)}`);
+      }
+    }
+  }
+  console.log();
+  return watched;
+}
+await draw();
+
+/**
+ * Redraw on change, because the point of a preview is the loop and not the picture. A module is
+ * re-imported under a fresh query string: Bun caches modules by specifier, so without it an edit
+ * would show the version from the first run forever.
+ */
+if (has("watch")) {
+  const files = [...modules.map(m => resolveModulePath(m, directory)), ...(configPath ? [configPath] : [])];
+  console.log(dim(`  watching ${files.length} file${files.length === 1 ? "" : "s"} — ctrl+c to stop\n`));
+  let pending;
+  for (const file of files) {
+    try {
+      watch(file, () => {
+        clearTimeout(pending);
+        // Editors save in bursts; redraw once the burst is over.
+        pending = setTimeout(() => {
+          void (async () => {
+            if (modules.length > 0) {
+              const again = await loadCustomSegments(modules, directory, path => import(`${path}?v=${Date.now()}`));
+              custom = again.segments;
+              for (const error of again.errors) console.error(`  module failed: ${error}`);
+            }
+            console.clear();
+            await draw();
+          })();
+        }, 120);
+      });
+    } catch {
+      // A file that cannot be watched is not a reason to stop previewing.
+    }
+  }
+}

package/dist/core/config.js

@@ -78,7 +78,7 @@ export function asStatusConfig(input) {
   const section = raw.statusline ?? raw.status;
   if (section && typeof section === "object") return section;
   const own = {};
-  for (const key of ["enabled", "surface", "segments", "separator", "stack", "icons", "lines", "commands", "modules"]) {
+  for (const key of ["enabled", "preset", "surface", "segments", "separator", "stack", "icons", "debug", "maxRows", "paddingLeft", "paddingRight", "paddingTop", "paddingBottom", "lines", "commands", "modules"]) {
     if (raw[key] !== undefined) Object.assign(own, {
       [key]: raw[key]
     });
@@ -132,6 +132,82 @@ export const DEFAULT_SEGMENTS = [{
   icon: ""
 }, "todo", "session.status", "diagnostics"];
 export const DEFAULT_SEPARATOR = " │ ";
+
+/**
+ * Whole lines, by the name of what you want.
+ *
+ * Composing a good statusline from fourteen segments is a design exercise, and most people want a
+ * good line rather than the exercise. Every preset is built-ins only — none needs a module, a
+ * command, or anything installed beside it.
+ */
+export const PRESETS = {
+  minimal: {
+    about: "how full the context is, and what changed",
+    surface: "bottom",
+    segments: [{
+      type: "context",
+      style: "bar",
+      width: 12,
+      icon: ""
+    }, {
+      type: "session.diff",
+      icon: ""
+    }, "session.status", "diagnostics"]
+  },
+  default: {
+    about: "the capacity bar, where the tokens went, what changed, how long",
+    surface: "bottom",
+    segments: DEFAULT_SEGMENTS
+  },
+  detailed: {
+    about: "everything the built-ins know, for a wide window",
+    surface: "bottom",
+    segments: [{
+      type: "context",
+      style: "split",
+      width: 14,
+      icon: ""
+    }, {
+      type: "tokens",
+      style: "parts",
+      icon: ""
+    }, {
+      type: "model",
+      icon: ""
+    }, "cost", {
+      type: "session.diff",
+      icon: ""
+    }, "todo", {
+      type: "session.time",
+      icon: ""
+    }, "session.status", "diagnostics"]
+  },
+  sidebar: {
+    about: "a quiet column beside OpenCode's own blocks",
+    surface: "sidebar",
+    segments: [{
+      type: "context",
+      style: "bar",
+      width: 14,
+      icon: ""
+    }, {
+      type: "tokens",
+      format: "tk {total}",
+      icon: ""
+    }, {
+      type: "tokens",
+      format: "cache {cacheRead}",
+      color: "success",
+      icon: ""
+    }, {
+      type: "session.diff",
+      icon: ""
+    }, {
+      type: "session.time",
+      icon: ""
+    }, "todo", "diagnostics"]
+  }
+};
 /** What each surface needs to sit level with the host's own content. */
 const PADDING = {
   // OpenCode's footer indents three columns, and a line hard against the bottom of the window
@@ -154,27 +230,33 @@ const PADDING = {
 /** Normalises whatever the config said into the lines the renderer draws. */
 export function resolveLines(config) {
   const lines = config.lines?.length ? config.lines : [{
+    preset: config.preset,
     surface: config.surface,
     segments: config.segments,
     separator: config.separator,
     stack: config.stack,
-    icons: config.icons
+    icons: config.icons,
+    debug: config.debug,
+    maxRows: config.maxRows
   }];
   return lines.map(line => {
-    const surface = line.surface ?? "bottom";
+    // A preset fills in what was not written; it never overrides what was.
+    const preset = PRESETS[line.preset ?? config.preset ?? ""];
+    const surface = line.surface ?? config.surface ?? preset?.surface ?? "bottom";
     // The sidebar is a narrow column: across, it would be three truncated words.
     const stack = line.stack ?? config.stack ?? (surface === "sidebar" ? "vertical" : "horizontal");
     return {
       surface,
-      segments: line.segments ?? config.segments ?? DEFAULT_SEGMENTS,
+      segments: line.segments ?? config.segments ?? preset?.segments ?? DEFAULT_SEGMENTS,
       separator: line.separator ?? config.separator ?? (stack === "vertical" ? "" : DEFAULT_SEPARATOR),
       stack,
-      maxRows: line.maxRows ?? 8,
+      maxRows: line.maxRows ?? config.maxRows ?? 8,
       icons: line.icons ?? config.icons ?? true,
-      paddingLeft: line.paddingLeft ?? PADDING[surface].left,
-      paddingRight: line.paddingRight ?? PADDING[surface].right,
-      paddingTop: line.paddingTop ?? PADDING[surface].top,
-      paddingBottom: line.paddingBottom ?? PADDING[surface].bottom
+      debug: line.debug ?? config.debug ?? false,
+      paddingLeft: line.paddingLeft ?? config.paddingLeft ?? PADDING[surface].left,
+      paddingRight: line.paddingRight ?? config.paddingRight ?? PADDING[surface].right,
+      paddingTop: line.paddingTop ?? config.paddingTop ?? PADDING[surface].top,
+      paddingBottom: line.paddingBottom ?? config.paddingBottom ?? PADDING[surface].bottom
     };
   });
 }

package/dist/core/custom.js

@@ -101,6 +101,8 @@ export async function loadCustomSegments(paths, directory, importer = path => im
           render(ctx, config) {
             const value = render(ctx, config);
             if (value === undefined) return undefined;
+            // Several rows: each is drawn on its own, and empty ones are left out.
+            if (Array.isArray(value)) return value.length > 0 ? value : undefined;
             if (typeof value === "string") return value ? {
               text: value,
               tone: "muted"

package/dist/core/fixtures.js

@@ -0,0 +1,157 @@
+/**
+ * Sample sessions to draw a statusline against, without an OpenCode to draw it in.
+ *
+ * Designing a statusline by editing TypeScript, restarting OpenCode and looking is a loop measured
+ * in minutes; one sidebar cost roughly twenty restarts. These are the states worth checking a
+ * design against — and the ones a design usually gets wrong, because they are the states you are
+ * not in while you are designing.
+ */
+
+const session = (over = {}) => ({
+  id: "ses_preview",
+  title: "A session",
+  status: "idle",
+  cost: 0.42,
+  priced: true,
+  messages: 8,
+  startedAt: 0,
+  model: {
+    providerID: "anthropic",
+    modelID: "claude-opus-5-20260101",
+    contextLimit: 200_000
+  },
+  tokens: {
+    input: 265,
+    output: 60,
+    reasoning: 0,
+    cache: {
+      read: 84_900,
+      write: 0
+    }
+  },
+  diff: {
+    files: 3,
+    additions: 42,
+    deletions: 7
+  },
+  todo: {
+    total: 5,
+    completed: 2
+  },
+  ...over
+});
+const base = (over = {}) => ({
+  now: 2 * 24 * 3600_000 + 15 * 3600_000,
+  directory: "/Users/you/code/checkout-service/src",
+  worktree: "/Users/you/code/checkout-service",
+  home: "/Users/you",
+  branch: "feature/checkout",
+  defaultBranch: "main",
+  version: "0.3.0",
+  lsp: [{
+    name: "tsserver",
+    status: "connected"
+  }],
+  mcp: [{
+    name: "github",
+    status: "connected"
+  }],
+  commands: {},
+  width: 120,
+  ...over
+});
+
+/** Each one is a state a design has to survive, not merely a different set of numbers. */
+export const FIXTURES = {
+  /** Before the first reply: no model, no tokens, no cost. Most designs render a wall of zeroes. */
+  fresh: {
+    about: "a new session, before the first reply",
+    ctx: base({
+      session: session({
+        messages: 0,
+        cost: 0,
+        priced: false,
+        model: undefined,
+        tokens: undefined,
+        diff: {
+          files: 0,
+          additions: 0,
+          deletions: 0
+        },
+        todo: {
+          total: 0,
+          completed: 0
+        }
+      })
+    })
+  },
+  /** The ordinary case: a few turns in, mostly cache. */
+  working: {
+    about: "a few turns in, mostly served from cache",
+    ctx: base({
+      session: session()
+    })
+  },
+  /** Nearly out of room, which is when the design has to shout. */
+  full: {
+    about: "the context nearly full, a long session",
+    ctx: base({
+      session: session({
+        cost: 26.24,
+        tokens: {
+          input: 4_200,
+          output: 2_100,
+          reasoning: 900,
+          cache: {
+            read: 181_000,
+            write: 3_400
+          }
+        },
+        diff: {
+          files: 28,
+          additions: 1_840,
+          deletions: 620
+        },
+        todo: {
+          total: 9,
+          completed: 9
+        }
+      })
+    })
+  },
+  /** Behind a proxy: tokens flow, but nobody declared prices or a window. */
+  unpriced: {
+    about: "behind a proxy — no declared prices or context window",
+    ctx: base({
+      session: session({
+        priced: false,
+        cost: 0,
+        model: {
+          providerID: "litellm",
+          modelID: "claude-opus-5"
+        }
+      })
+    })
+  },
+  /** Stalled, which OpenCode itself shows only as a spinner. */
+  retrying: {
+    about: "a stalled turn, retrying",
+    ctx: base({
+      now: 1_000,
+      session: session({
+        status: "retry",
+        startedAt: 0,
+        retry: {
+          attempt: 2,
+          message: "rate limited",
+          next: 6_000
+        }
+      })
+    })
+  },
+  /** Off a session route entirely: everything session-shaped must stay quiet. */
+  empty: {
+    about: "no session at all",
+    ctx: base()
+  }
+};