@opencode-cockpit/status 0.3.0 → 0.3.1

package/examples/sidebar.ts

@@ -0,0 +1,82 @@
+/**
+ * A small, quiet sidebar: a coloured context bar and the two figures behind it.
+ *
+ * The sidebar sits beside OpenCode's own Context block, which already gives you the token count,
+ * the percentage and the spend. So this one does not repeat them -- it draws the bar those numbers
+ * describe, and adds the two things the host leaves out: how the window is being used, and what
+ * the session has changed.
+ *
+ *   {
+ *     "statusline": {
+ *       "modules": ["<this file>"],
+ *       "surface": "sidebar",
+ *       "segments": ["bar", "split", "changes"]
+ *     }
+ *   }
+ *
+ * `stack` defaults to vertical here, so it does not need to be written.
+ */
+
+import type { CustomModule, Run, StatusContext } from "@opencode-cockpit/status/segment"
+import { compact, contextRatio, contextUsed, gradient } from "@opencode-cockpit/status/segment"
+
+/** A row with a quiet label, so a column of them lines up as a table would. */
+function row(label: string, value: Run[]): { runs: Run[] } {
+  return { runs: [{ text: `${label} `, tone: "muted", dim: true }, ...value] }
+}
+
+export default {
+  segments: {
+    /**
+     * The context window, coloured cell by cell. The figure beside it is the host's own, so this
+     * is the one place the bay repeats something -- a bar with no number is hard to read at a
+     * glance, and the percentage is two characters.
+     */
+    bar(ctx: StatusContext, config) {
+      const ratio = contextRatio(ctx.session)
+      if (ratio === undefined) return undefined
+      const width = typeof config.width === "number" ? config.width : 14
+      const filled = Math.round(ratio * width)
+      const runs: Run[] = []
+      for (let cell = 0; cell < width; cell++) {
+        runs.push(
+          cell < filled
+            ? { text: "█", color: gradient((cell + 1) / width) }
+            : { text: "░", tone: "border" as const },
+        )
+      }
+      runs.push({ text: ` ${Math.round(ratio * 100)}%`, color: gradient(ratio) })
+      return { runs }
+    },
+
+    /**
+     * What the window is made of: cache, fresh input, output. A coloured rule per part rather
+     * than a filled chip, so a share of nothing is a mark rather than an empty box.
+     */
+    split(ctx: StatusContext) {
+      const tokens = ctx.session?.tokens
+      const total = contextUsed(tokens)
+      if (!tokens || total === 0) return undefined
+      const share = (n: number) => `${Math.round((n / total) * 100)}%`
+      return row("split", [
+        { text: "▌", tone: "success" },
+        { text: share(tokens.cache.read + tokens.cache.write), tone: "muted" },
+        { text: " ▌", tone: "info" },
+        { text: share(tokens.input), tone: "muted" },
+        { text: " ▌", tone: "accent" },
+        { text: share(tokens.output + tokens.reasoning), tone: "muted" },
+      ])
+    },
+
+    /** What the session has done to the working tree, which the host never mentions. */
+    changes(ctx: StatusContext) {
+      const diff = ctx.session?.diff
+      if (!diff || diff.files === 0) return undefined
+      return row("diff", [
+        { text: `${diff.files}f`, tone: "muted" },
+        { text: ` +${compact(diff.additions)}`, tone: "success" },
+        { text: ` -${compact(diff.deletions)}`, tone: "error" },
+      ])
+    },
+  },
+} satisfies CustomModule

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-cockpit/status",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "A statusline for OpenCode you can actually configure: declarative segments, a typed module, or your existing Claude Code statusline command",
   "type": "module",
   "license": "MIT",
@@ -35,6 +35,10 @@
     "./segment": {
       "types": "./types/core/authoring.d.ts",
       "default": "./dist/core/authoring.js"
+    },
+    "./fixtures": {
+      "types": "./types/core/fixtures.d.ts",
+      "default": "./dist/core/fixtures.js"
     }
   },
   "engines": {
@@ -44,6 +48,8 @@
   "files": [
     "dist",
     "types",
+    "examples",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -51,7 +57,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@opencode-cockpit/client": "0.3.0",
+    "@opencode-cockpit/client": "0.3.1",
     "@opencode-ai/plugin": "1.18.31"
   },
   "devDependencies": {
@@ -59,5 +65,8 @@
     "@opentui/keymap": "0.4.5",
     "@opentui/solid": "0.4.5",
     "solid-js": "1.9.12"
+  },
+  "bin": {
+    "opencode-statusline": "./dist/cli/preview.js"
   }
 }

package/skills/statusline-design/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: statusline-design
+description: Designing or editing an opencode-cockpit statusline — a bottom line or a sidebar column, its config, or a TypeScript segment module. Use when a request mentions the statusline, a segment, .cockpit.json's statusline section, or a module importing @opencode-cockpit/status/segment.
+---
+
+# Designing a statusline
+
+A statusline is a **visual artifact judged in a terminal**. The failure mode this skill exists to
+prevent is designing it blind: editing TypeScript, restarting OpenCode, and scoring the result from
+a sentence. One sidebar took about twenty restarts and five rejected iterations that way, and three
+of the rejections were glyph choices that read completely differently on screen than they do in
+prose.
+
+## Look at it before you ship it
+
+```sh
+bunx @opencode-cockpit/status preview --watch          # redraws on every save
+bunx @opencode-cockpit/status preview --state full     # one state
+bunx @opencode-cockpit/status preview --debug          # mark segments that drew nothing
+```
+
+The preview draws the real segments against sample sessions, in this terminal, with no OpenCode
+involved. **Use it after every change.** If a design decision cannot be checked in the preview, it
+has not been checked.
+
+Before writing code for anything visual, **paste an ASCII mock and ask**. A mock costs a line; a
+wrong reading of one ambiguous word costs two iterations. "Make it taller" once meant "make the bar
+look solid", and the two interpretations share no code.
+
+## Rules with reasons
+
+| Rule | Why |
+| --- | --- |
+| **Never repeat what OpenCode already shows.** Its footer has path, branch, token total, spend; its prompt has agent and model. | Configured carelessly the same percentage lands on screen five times. The exception: a *better instrument* for the same fact — a bar you read without looking is not a second copy of `78.5K (39%)`. |
+| **A segment with nothing to say says nothing.** | `cost` hides where no prices are declared rather than printing `$0.00`; `context` hides with no declared window rather than inventing a denominator. A confident wrong number is worse than an absent one. |
+| **No walls of zeroes on a fresh session.** Check the `fresh` and `empty` fixtures. | Most designs look right mid-session and read as broken before the first reply. |
+| **Every number gets a word.** Colour may repeat the meaning, never carry it alone. | A row distinguished only by colour is unreadable: "I read `mix` and I don't understand the colours." |
+| **Labels in a fixed-width column, values after.** | Alignment is what makes a column read as designed rather than as output. |
+| **Bars are solid.** Filled cells `█` coloured by level; the empty track is `█` in `panel` tone. | `░` reads as floating gaps and `─` reads as `-----`. Both were rejected on sight. Swapping one rejected glyph for another is not iteration. |
+| **Single-width glyphs only.** | An emoji is two cells in most terminals and one in a few — exactly what shears a fixed-width line. |
+| **Prefer a coloured rule `▌` to a filled pill.** | A filled block must be as wide as its text, so a short label leaves a slab of colour and an empty one leaves an empty box. |
+| **Prefer a figure to a moving picture.** | A sparkline redraws its shape every second; movement in peripheral vision is the one thing a statusline must not do. `+1.2%/min · 48m left` changes digits and nothing else. |
+| **No section headings above optional rows.** | A heading cannot know whether the rows under it will draw, so `SPEND` strands itself above nothing on an unpriced model. Self-label the rows instead. |
+| **Emphasis is a bonus, never the meaning.** Bold, italic and underline are `<b>`, `<i>`, `<u>` markup — and a terminal with no bold face draws bold identically to plain. | Colour and background always render; weight may not. There is no strikethrough or inverse at all. |
+| **Colours come from tones, not hexes.** `text muted accent success warning error info background panel border` | A literal ignores the user's theme, which is the first thing that makes a plugin look bolted on. Use a hex only where the exact colour *is* the meaning. |
+| **Say what a number means in the word, not the docs.** `cache` is cache reads, `write` is cache writes, `in` is fresh prompt tokens, `out` is output plus reasoning. | Read and write are not in and out; a reader who has to learn your mapping will misread it. |
+
+## The renderer's contract
+
+- One segment draws **one row**, unless it returns an **array** of pieces — then each element is a
+  row of its own. (Arrays used to be silently dropped; they work now.)
+- A segment returns a string, `{ text, tone, color }`, `{ runs: [...] }`, an array of those, or
+  `undefined` to say nothing.
+- A run takes `tone`, `color`, `bg`, `bgTone`, `bold`, `dim`, `italic`, `underline`.
+- **A track drawn in `panel` tone is invisible** on most themes — it is the panel's own colour.
+  Use `border`.
+- A **column** keeps at most `maxRows` rows (default 8) — **count your rows and raise it**, or the
+  extras vanish. The preview prints `↳ N dropped` when this happens.
+- A **line** drops the lowest-priority segments until it fits the width.
+- A segment that throws loses only its own row. A module that fails to load raises a toast naming
+  the file.
+
+## Checking what actually reached the terminal
+
+`preview` paints with its own ANSI and the smoke harness serialises the screen as text, so both are
+blind to colour and emphasis. When a design looks wrong and the code looks right:
+
+```sh
+bun run capture --sidebar --find "40%" --find bold
+```
+
+It drives a real OpenCode and reports the escape codes written around the text you name. That is
+how three separate "is this even working" questions were settled in minutes rather than rounds:
+bold *was* being emitted and the font had no bold face; italic *was* being emitted and the word was
+truncated; a track *was* being drawn and `panel` was the panel's own colour.
+
+## Where everything lives
+
+| What | Where |
+| --- | --- |
+| Settings, every project | `~/.config/opencode-cockpit/config.json` |
+| Settings, one project | `<project>/.cockpit.json` |
+| Modules | anywhere — `~/.config/opencode-cockpit/modules/` needs no `node_modules` beside it |
+| Which plugins load | `~/.config/opencode/tui.json` |
+
+## Turning OpenCode's own blocks off
+
+Each block of the host's sidebar is an internal plugin, and `tui.json` disables any of them:
+
+```jsonc
+{ "plugin": ["opencode-cockpit"], "plugin_enabled": { "internal:sidebar-context": false } }
+```
+
+`internal:sidebar-{context,files,todo,lsp,mcp,footer}`, `internal:home-{footer,tips}`,
+`internal:notifications`. **A sidebar meant to replace the Context block must carry what that block
+carried** — percentage, token total, spend — or the user ends up with less than before.
+
+The footer under the prompt is core UI: it cannot be hidden. Design around it.
+
+## Start simple
+
+Most people want a good line, not a composition exercise. Begin with the built-ins and a `format`
+string; reach for a module only when the answer needs the session read, decided on, or remembered
+across ticks — a rate, a trend, a budget from a file. Reach for a shell `command` for anything a CLI
+already prints; do not reimplement the shell as a segment.

package/types/cli/ansi.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+import type { Run } from "../core/types.ts";
+export declare function paint(run: Run): string;
+export declare function paintRuns(runs: readonly Run[]): string;

package/types/cli/preview.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+export {};

package/types/core/config.d.ts

@@ -52,6 +52,8 @@ export interface CommandConfig {
  */
 export type Stack = "horizontal" | "vertical";
 export interface LineConfig {
+    /** A whole line by name; anything written beside it wins. */
+    preset?: string;
     surface?: Surface;
     segments?: (string | SegmentConfig)[];
     /** Drawn between segments. Defaults to " · " across, and nothing down. */
@@ -60,6 +62,8 @@ export interface LineConfig {
     stack?: Stack;
     /** Built-in icons. On by default; switch off for a terminal missing the glyphs. */
     icons?: boolean;
+    /** Draw a placeholder where a segment said nothing, so a typo and missing data look different. */
+    debug?: boolean;
     /** Vertical only: rows to draw at most. Lowest priority goes first. Defaults to 8. */
     maxRows?: number;
     /**
@@ -74,6 +78,11 @@ export interface LineConfig {
 }
 export interface StatusConfig {
     enabled?: boolean;
+    /**
+     * A whole line by name: `minimal`, `default`, `detailed`, `sidebar`. Anything you write
+     * alongside it wins, so a preset is a starting point rather than a mode.
+     */
+    preset?: string;
     /** One line, for the common case. Use `lines` for more than one surface. */
     surface?: Surface;
     segments?: (string | SegmentConfig)[];
@@ -81,6 +90,18 @@ export interface StatusConfig {
     stack?: Stack;
     /** Built-in icons. On by default; switch off for a terminal missing the glyphs. */
     icons?: boolean;
+    /** Draw a placeholder where a segment said nothing, so a typo and missing data look different. */
+    debug?: boolean;
+    /**
+     * Vertical lines: rows to draw at most. Settable here as well as per line, because writing it
+     * here is the natural guess and having it quietly ignored costs exactly the rows it was meant
+     * to keep.
+     */
+    maxRows?: number;
+    paddingLeft?: number;
+    paddingRight?: number;
+    paddingTop?: number;
+    paddingBottom?: number;
     lines?: LineConfig[];
     /** Named commands usable as segments: `{"type": "command", "name": "budget"}`. */
     commands?: Record<string, CommandConfig>;
@@ -123,6 +144,18 @@ export declare function asStatusConfig(input: unknown): StatusConfig;
  */
 export declare const DEFAULT_SEGMENTS: (string | SegmentConfig)[];
 export declare const DEFAULT_SEPARATOR = " \u2502 ";
+/**
+ * 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 declare const PRESETS: Record<string, {
+    about: string;
+    surface: Surface;
+    segments: (string | SegmentConfig)[];
+}>;
 export interface ResolvedLine {
     surface: Surface;
     segments: (string | SegmentConfig)[];
@@ -130,6 +163,7 @@ export interface ResolvedLine {
     stack: Stack;
     maxRows: number;
     icons: boolean;
+    debug: boolean;
     paddingLeft: number;
     paddingRight: number;
     paddingTop: number;

package/types/core/custom.d.ts

@@ -1,6 +1,6 @@
 import type { SegmentConfig } from "./config.ts";
 import type { StatusContext } from "./context.ts";
-import type { Run, SegmentDef, Tone } from "./segments.ts";
+import type { Piece, Run, SegmentDef, Tone } from "./segments.ts";
 /**
  * Your own segments, written in TypeScript.
  *
@@ -32,7 +32,7 @@ export type CustomRender = (ctx: StatusContext, config: SegmentConfig) => {
     color?: string;
 } | {
     runs: Run[];
-} | string | undefined;
+} | Piece[] | string | undefined;
 export interface CustomModule {
     segments?: Record<string, CustomRender | {
         render: CustomRender;

package/types/core/fixtures.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ */
+import type { StatusContext } from "./context.ts";
+export type FixtureName = "fresh" | "working" | "full" | "unpriced" | "retrying" | "empty";
+/** Each one is a state a design has to survive, not merely a different set of numbers. */
+export declare const FIXTURES: Record<FixtureName, {
+    about: string;
+    ctx: StatusContext;
+}>;

package/types/core/segments.d.ts

@@ -6,7 +6,7 @@ import type { Piece, Run, Segment, SegmentDef } from "./types.ts";
  * Turning a line's configuration into the segments a surface draws. The segment model itself lives
  * in `types.ts` and the built-ins in `builtins/`; this file is only the assembly.
  */
-export type { Piece, Run, Segment, SegmentDef, Tone } from "./types.ts";
+export type { Piece, Pieces, Run, Segment, SegmentDef, Tone } from "./types.ts";
 export { BUILTINS };
 export declare function runsOf(piece: Piece): Run[];
 export declare function segmentText(segment: Segment): string;
@@ -22,5 +22,14 @@ export interface BuildOptions {
     custom?: ReadonlyMap<string, SegmentDef>;
     /** Icons are on by default; a terminal without the glyphs can switch them off. */
     icons?: boolean;
+    /**
+     * Draw a placeholder where a segment chose to say nothing, and mark names nothing answers to.
+     *
+     * The rule that a segment with nothing to say says nothing is right while you are working and
+     * miserable while you are configuring: a typo, a proxy that declared no context window, and a
+     * model with no prices all look identical, because all three look like absence. This makes the
+     * three distinguishable for as long as it is on.
+     */
+    debug?: boolean;
 }
 export declare function buildSegments(ctx: StatusContext, configs: SegmentConfig[], options?: BuildOptions | ReadonlyMap<string, SegmentDef>): Segment[];

package/types/core/types.d.ts

@@ -22,14 +22,21 @@ export interface Run {
     bgTone?: Tone;
     bold?: boolean;
     dim?: boolean;
+    italic?: boolean;
+    underline?: boolean;
 }
+/**
+ * Emphasis stops here on purpose. OpenTUI draws bold, italic and underline as markup (`<b>`,
+ * `<i>`, `<u>`) and offers no element for strikethrough or inverse, so neither was ever going to
+ * reach the screen. To make a run shout, give it a background: `bgTone` always renders.
+ */
 export interface Segment {
     id: string;
     runs: Run[];
     /** Higher survives when the line is too long for the terminal. */
     priority: number;
 }
-/** What a segment may return: one styled string, or several. */
+/** What a segment may return: one styled string, or several runs. */
 export type Piece = {
     text: string;
     tone?: Tone;
@@ -37,6 +44,14 @@ export type Piece = {
 } | {
     runs: Run[];
 };
+/**
+ * A segment may also answer with several rows — a gauge with bands, a row per service, a table.
+ * Down a column each becomes its own row; across a line they sit next to each other.
+ *
+ * Returning an array used to be a silent no-op, which is an expensive thing to debug: the segment
+ * ran, returned something reasonable, and drew nothing at all.
+ */
+export type Pieces = Piece | Piece[];
 /**
  * A built-in. Returning `undefined` hides it, and that is the important half of the contract:
  * a segment whose input is missing must say nothing. A cost of "$0.00" on a provider nobody
@@ -48,5 +63,5 @@ export interface SegmentDef {
     priority: number;
     /** Shown before the text when icons are on. */
     icon?: string;
-    render(ctx: StatusContext, config: SegmentConfig): Piece | undefined;
+    render(ctx: StatusContext, config: SegmentConfig): Pieces | undefined;
 }

package/types/tui/components/statusline.d.ts

@@ -1,5 +1,6 @@
 /** @jsxImportSource @opentui/solid */
 import type { TuiPluginApi, TuiThemeCurrent } from "@opencode-ai/plugin/tui";
+import type { JSX } from "solid-js";
 import type { Segment, Tone } from "../../core/segments.ts";
 /**
  * One line of segments, each segment a list of styled runs. Colour comes from the running theme
@@ -23,4 +24,4 @@ export interface StatusLineProps {
     paddingTop?: number;
     paddingBottom?: number;
 }
-export declare function StatusLine(props: StatusLineProps): import("solid-js").JSX.Element;
+export declare function StatusLine(props: StatusLineProps): JSX.Element;