@opencode-cockpit/status 0.3.0 → 0.3.1

package/dist/core/segments.js

@@ -78,7 +78,8 @@ export function buildSegments(ctx, configs, options = {}) {
   // A bare map is accepted so the common case reads as `buildSegments(ctx, configs, custom)`.
   const {
     custom,
-    icons = true
+    icons = true,
+    debug = false
   } = options instanceof Map ? {
     custom: options
   } : options;
@@ -87,58 +88,92 @@ export function buildSegments(ctx, configs, options = {}) {
   for (const config of configs) {
     // Your own segments are looked up first, so a module can replace a built-in by name.
     const def = custom?.get(config.type) ?? findSegment(config.type);
-    if (!def) continue;
+    if (!def) {
+      // A name nothing answers to: a typo, or a segment from a module that failed to load.
+      if (debug) out.push(marker(`?${config.type}`, "error", config.type, seen));
+      continue;
+    }
     let piece;
     try {
       piece = def.render(ctx, config);
     } catch {
-      continue; // a segment that throws costs its own place on the line and nothing else
+      // A segment that throws costs its own place on the line and nothing else.
+      if (debug) out.push(marker(`!${config.type}`, "error", config.type, seen));
+      continue;
+    }
+    if (!piece) {
+      // It ran and chose silence: the input it needs is missing, not its name.
+      if (debug) out.push(marker(config.type, "border", config.type, seen));
+      continue;
     }
-    if (!piece) continue;
     const wanted = typeof config.color === "string" ? config.color : undefined;
     const forcedTone = wanted ? toTone(wanted) : undefined;
     const forcedColor = wanted && isLiteralColor(wanted) ? wanted : undefined;
-    const runs = runsOf(piece).filter(run => run.text.length > 0);
-    if (runs.length === 0) continue;
-    const icon = typeof config.icon === "string" ? config.icon : icons ? def.icon : undefined;
-    const prefix = typeof config.prefix === "string" ? config.prefix : "";
-    const suffix = typeof config.suffix === "string" ? config.suffix : "";
-    // The icon gets its own run so it can be dimmed apart from the value it labels.
-    if (icon) runs.unshift({
-      text: `${icon} `,
-      tone: runs[0]?.tone,
-      dim: true
-    });
-    if (prefix) runs.unshift({
-      text: prefix,
-      tone: runs[0]?.tone
-    });
-    if (suffix) runs.push({
-      text: suffix,
-      tone: runs[runs.length - 1]?.tone
-    });
 
-    // A colour named on the segment overrides every run in it, icon included; that is what makes
-    // `{"type": "cost", "color": "#ff8800"}` do what it looks like it should.
-    const styled = forcedTone || forcedColor ? runs.map(run => ({
-      ...run,
-      ...(forcedTone ? {
-        tone: forcedTone
-      } : {}),
-      ...(forcedColor ? {
-        color: forcedColor
-      } : {})
-    })) : runs;
-    const count = (seen.get(config.type) ?? 0) + 1;
-    seen.set(config.type, count);
-    out.push({
-      id: count === 1 ? config.type : `${config.type}#${count}`,
-      runs: styled,
-      priority: typeof config.priority === "number" ? config.priority : def.priority
-    });
+    // Several rows are placed one after another: down a column each is a row of its own.
+    const pieces = Array.isArray(piece) ? piece : [piece];
+    let drew = false;
+    for (const one of pieces) {
+      const runs = runsOf(one).filter(run => run.text.length > 0);
+      if (runs.length === 0) continue;
+      const icon = typeof config.icon === "string" ? config.icon : icons ? def.icon : undefined;
+      const prefix = typeof config.prefix === "string" ? config.prefix : "";
+      const suffix = typeof config.suffix === "string" ? config.suffix : "";
+      // The icon gets its own run so it can be dimmed apart from the value it labels.
+      if (icon) runs.unshift({
+        text: `${icon} `,
+        tone: runs[0]?.tone,
+        dim: true
+      });
+      if (prefix) runs.unshift({
+        text: prefix,
+        tone: runs[0]?.tone
+      });
+      if (suffix) runs.push({
+        text: suffix,
+        tone: runs[runs.length - 1]?.tone
+      });
+
+      // A colour named on the segment overrides every run in it, icon included; that is what makes
+      // `{"type": "cost", "color": "#ff8800"}` do what it looks like it should.
+      const styled = forcedTone || forcedColor ? runs.map(run => ({
+        ...run,
+        ...(forcedTone ? {
+          tone: forcedTone
+        } : {}),
+        ...(forcedColor ? {
+          color: forcedColor
+        } : {})
+      })) : runs;
+      const count = (seen.get(config.type) ?? 0) + 1;
+      seen.set(config.type, count);
+      out.push({
+        id: count === 1 ? config.type : `${config.type}#${count}`,
+        runs: styled,
+        priority: typeof config.priority === "number" ? config.priority : def.priority
+      });
+      drew = true;
+    }
+    if (!drew && debug) out.push(marker(config.type, "border", config.type, seen));
   }
   return out;
 }
+
+/** What a silent segment looks like while `debug` is on. */
+function marker(text, tone, type, seen) {
+  const count = (seen.get(type) ?? 0) + 1;
+  seen.set(type, count);
+  return {
+    id: count === 1 ? type : `${type}#${count}`,
+    runs: [{
+      text: `⟨${text}⟩`,
+      tone,
+      dim: true
+    }],
+    // Above everything, so the thing you are debugging is not the first dropped when it is narrow.
+    priority: 100
+  };
+}
 const TONES = new Set(["text", "muted", "accent", "success", "warning", "error", "info"]);
 function toTone(value) {
   return TONES.has(value) ? value : undefined;

package/dist/tui/components/statusline.js

@@ -1,9 +1,9 @@
 import { insertNode as _$insertNode } from "@opentui/solid";
 import { memo as _$memo } from "@opentui/solid";
 import { effect as _$effect } from "@opentui/solid";
-import { insert as _$insert } from "@opentui/solid";
 import { createComponent as _$createComponent } from "@opentui/solid";
 import { setProp as _$setProp } from "@opentui/solid";
+import { insert as _$insert } from "@opentui/solid";
 import { createElement as _$createElement } from "@opentui/solid";
 /** @jsxImportSource @opentui/solid */
 
@@ -56,13 +56,40 @@ function runStyle(theme, run) {
     fg
   };
 }
+
+/**
+ * Emphasis is markup, not a style property.
+ *
+ * OpenTUI draws bold, italic and underline through `<b>`, `<i>` and `<u>` around the text — there
+ * is no attribute to set. Passing one as a prop on the span type-checks and renders nothing at
+ * all, which is how every attribute disappeared at once while the colours kept working.
+ */
+function decorate(run) {
+  let node = run.text;
+  if (run.underline) node = (() => {
+    var _el$ = _$createElement("u");
+    _$insert(_el$, node);
+    return _el$;
+  })();
+  if (run.italic) node = (() => {
+    var _el$2 = _$createElement("i");
+    _$insert(_el$2, node);
+    return _el$2;
+  })();
+  if (run.bold) node = (() => {
+    var _el$3 = _$createElement("b");
+    _$insert(_el$3, node);
+    return _el$3;
+  })();
+  return node;
+}
 export function StatusLine(props) {
   const theme = () => props.api.theme.current;
   const down = () => props.stack === "vertical";
   return (() => {
-    var _el$ = _$createElement("box");
-    _$setProp(_el$, "flexShrink", 0);
-    _$insert(_el$, _$createComponent(For, {
+    var _el$4 = _$createElement("box");
+    _$setProp(_el$4, "flexShrink", 0);
+    _$insert(_el$4, _$createComponent(For, {
       get each() {
         return props.segments();
       },
@@ -71,18 +98,18 @@ export function StatusLine(props) {
           return _$memo(() => !!(index() > 0 && !down()))() && props.separator.length > 0;
         },
         get children() {
-          var _el$2 = _$createElement("text");
-          _$setProp(_el$2, "wrapMode", "none");
-          _$setProp(_el$2, "flexShrink", 0);
-          _$insert(_el$2, () => props.separator);
-          _$effect(_$p => _$setProp(_el$2, "fg", theme().borderSubtle, _$p));
-          return _el$2;
+          var _el$5 = _$createElement("text");
+          _$setProp(_el$5, "wrapMode", "none");
+          _$setProp(_el$5, "flexShrink", 0);
+          _$insert(_el$5, () => props.separator);
+          _$effect(_$p => _$setProp(_el$5, "fg", theme().borderSubtle, _$p));
+          return _el$5;
         }
       }), (() => {
-        var _el$3 = _$createElement("text");
-        _$setProp(_el$3, "wrapMode", "none");
-        _$setProp(_el$3, "flexShrink", 0);
-        _$insert(_el$3, _$createComponent(For, {
+        var _el$6 = _$createElement("text");
+        _$setProp(_el$6, "wrapMode", "none");
+        _$setProp(_el$6, "flexShrink", 0);
+        _$insert(_el$6, _$createComponent(For, {
           get each() {
             return segment.runs;
           },
@@ -92,23 +119,23 @@ export function StatusLine(props) {
             },
             get fallback() {
               return (() => {
-                var _el$6 = _$createElement("span");
-                _$insert(_el$6, () => run.text);
-                _$effect(_$p => _$setProp(_el$6, "style", runStyle(theme(), run), _$p));
-                return _el$6;
+                var _el$9 = _$createElement("span");
+                _$insert(_el$9, () => decorate(run));
+                _$effect(_$p => _$setProp(_el$9, "style", runStyle(theme(), run), _$p));
+                return _el$9;
               })();
             },
             get children() {
-              var _el$4 = _$createElement("span"),
-                _el$5 = _$createElement("b");
-              _$insertNode(_el$4, _el$5);
-              _$insert(_el$5, () => run.text);
-              _$effect(_$p => _$setProp(_el$4, "style", runStyle(theme(), run), _$p));
-              return _el$4;
+              var _el$7 = _$createElement("span"),
+                _el$8 = _$createElement("b");
+              _$insertNode(_el$7, _el$8);
+              _$insert(_el$8, () => run.text);
+              _$effect(_$p => _$setProp(_el$7, "style", runStyle(theme(), run), _$p));
+              return _el$7;
             }
           })
         }));
-        return _el$3;
+        return _el$6;
       })()]
     }));
     _$effect(_p$ => {
@@ -117,11 +144,11 @@ export function StatusLine(props) {
         _v$3 = props.paddingRight ?? 1,
         _v$4 = props.paddingTop ?? 0,
         _v$5 = props.paddingBottom ?? 0;
-      _v$ !== _p$.e && (_p$.e = _$setProp(_el$, "flexDirection", _v$, _p$.e));
-      _v$2 !== _p$.t && (_p$.t = _$setProp(_el$, "paddingLeft", _v$2, _p$.t));
-      _v$3 !== _p$.a && (_p$.a = _$setProp(_el$, "paddingRight", _v$3, _p$.a));
-      _v$4 !== _p$.o && (_p$.o = _$setProp(_el$, "paddingTop", _v$4, _p$.o));
-      _v$5 !== _p$.i && (_p$.i = _$setProp(_el$, "paddingBottom", _v$5, _p$.i));
+      _v$ !== _p$.e && (_p$.e = _$setProp(_el$4, "flexDirection", _v$, _p$.e));
+      _v$2 !== _p$.t && (_p$.t = _$setProp(_el$4, "paddingLeft", _v$2, _p$.t));
+      _v$3 !== _p$.a && (_p$.a = _$setProp(_el$4, "paddingRight", _v$3, _p$.a));
+      _v$4 !== _p$.o && (_p$.o = _$setProp(_el$4, "paddingTop", _v$4, _p$.o));
+      _v$5 !== _p$.i && (_p$.i = _$setProp(_el$4, "paddingBottom", _v$5, _p$.i));
       return _p$;
     }, {
       e: undefined,
@@ -130,6 +157,6 @@ export function StatusLine(props) {
       o: undefined,
       i: undefined
     });
-    return _el$;
+    return _el$4;
   })();
 }

package/dist/tui/index.js

@@ -40,7 +40,13 @@ export function createStatusTui({
     if (config.modules?.length) {
       const loaded = await loadCustomSegments(config.modules, directory);
       custom = loaded.segments;
-      // A module that will not load is worth saying out loud: its segments silently vanish.
+      /**
+       * A module that will not load is worth saying out loud twice over: its segments simply are
+       * not there, which looks exactly like a plugin that did nothing. The toast is gone in ten
+       * seconds, so the reason also goes to OpenCode's log, where it can still be read afterwards
+       * — a whole session was once spent diagnosing an import that had already explained itself
+       * and then disappeared.
+       */
       for (const error of loaded.errors) {
         api.ui.toast({
           variant: "error",
@@ -48,6 +54,11 @@ export function createStatusTui({
           message: error,
           duration: 10_000
         });
+        void api.client.app.log({
+          service: "opencode-cockpit.status",
+          level: "error",
+          message: `statusline module failed to load: ${error}`
+        }).catch(() => {});
       }
     }
     const lines = resolveLines(config);
@@ -62,7 +73,8 @@ export function createStatusTui({
       const segments = createMemo(() => {
         const built = buildSegments(store.context(), spec.segments.map(asSegmentConfig), {
           custom,
-          icons: spec.icons
+          icons: spec.icons,
+          debug: spec.debug
         });
         return spec.stack === "vertical" ? fitColumn(built, width(), spec.maxRows).segments : fit(built, width(), spec.separator).segments;
       });

package/examples/README.md

@@ -0,0 +1,60 @@
+# Examples
+
+Start with a **preset** — a whole line by name, built-ins only, nothing to install:
+
+```jsonc
+// ~/.config/opencode-cockpit/config.json
+{ "statusline": { "preset": "default" } }
+```
+
+| Preset | Surface | What you get |
+| --- | --- | --- |
+| `minimal` | bottom | how full the context is, and what changed |
+| `default` | bottom | the bar, where the tokens went, what changed, how long |
+| `detailed` | bottom | everything the built-ins know, for a wide window |
+| `sidebar` | sidebar | a quiet column beside OpenCode's own blocks |
+
+Anything you write beside a preset wins, so it is a starting point rather than a mode:
+
+```jsonc
+{ "statusline": { "preset": "default", "separator": "  " } }
+```
+
+## When a preset is not enough
+
+These are modules — TypeScript you copy and cut. Point `modules` at one and use its segments by
+name. Every one is loaded and asserted by the test suite, so none of them can rot.
+
+| File | For | Segments |
+| --- | --- | --- |
+| [`bottom.ts`](./bottom.ts) | the whole statusline on one line, no sidebar open | `bar` `filling` `rate` `cached` `tokens` |
+| [`sidebar.ts`](./sidebar.ts) | a small column **beside** OpenCode's Context block | `bar` `split` `changes` |
+| [`sidebar-full.ts`](./sidebar-full.ts) | a column that **replaces** that block — turn it off with `plugin_enabled` | `bar` `window` `cached` `spend` `elapsed` `changes` `todo` |
+| [`sidebar-budget.ts`](./sidebar-budget.ts) | a column as a **table**: fixed label gutter, one bar, a proxy's budget, the branch diff | `title` `bar` `tokens` `in` `out` `cache` `write` `sep` `spend` `avail` `git` |
+| [`gallery.ts`](./gallery.ts) | not a statusline — every technique the renderer can draw, labelled | all of them |
+
+```jsonc
+{
+  "statusline": {
+    "modules": ["~/.config/opencode-cockpit/modules/bottom.ts"],
+    "surface": "bottom",
+    "segments": ["bar", "filling", "rate", "cached", "session.diff", "session.time"]
+  }
+}
+```
+
+## Look at it before you ship it
+
+```sh
+bunx @opencode-cockpit/status preview --watch            # redraws on every save
+bunx @opencode-cockpit/status preview --state fresh      # before the first reply
+bunx @opencode-cockpit/status preview --debug            # mark segments that drew nothing
+bunx @opencode-cockpit/status preview --module examples/gallery.ts
+```
+
+The six sample sessions are the states a design gets wrong: `fresh` (no model, no tokens — most
+designs render a wall of zeroes), `working`, `full`, `unpriced` (behind a proxy, nothing declared),
+`retrying`, and `empty`.
+
+The taste rules this bay learned the expensive way live in
+[`../skills/statusline-design/`](../skills/statusline-design/SKILL.md).

package/examples/bottom.ts

@@ -0,0 +1,150 @@
+/**
+ * Everything on one line, for a window with no sidebar open.
+ *
+ * Every segment here reads the session snapshot, which is the line this bay draws: anything a CLI
+ * can already print belongs in a `command`, shaped in the shell, not in a segment that duplicates
+ * it. The working tree, for instance, needs no code from us at all:
+ *
+ *   "commands": { "tree": { "run": "git diff --shortstat | awk '{print \"+\"$4\" -\"$6}'" } }
+ *
+ * This is the whole statusline for someone who lives in the bottom line: how full the context is,
+ * which way it is going, what the session has changed, and whether anything needs them. It is the
+ * densest of the examples on purpose -- the bottom line is the only surface with real width.
+ *
+ *   {
+ *     "statusline": {
+ *       "modules": ["<this file>"],
+ *       "lines": [
+ *         { "surface": "bottom", "separator": " │ ",
+ *           "segments": ["bar", "filling", "rate", "cached", "session.diff", "todo",
+ *                        "session.time", "diagnostics"] }
+ *       ]
+ *     }
+ *   }
+ *
+ * Two lines on the same surface stack, if you would rather split it in two rows.
+ */
+
+import type { CustomModule, Run, StatusContext } from "@opencode-cockpit/status/segment"
+import { compact, contextRatio, contextUsed, gradient } from "@opencode-cockpit/status/segment"
+
+/** Samples kept between ticks: the shape of a session is not visible in any single reading. */
+const samples: { at: number; ratio: number; cost: number }[] = []
+
+function sample(ctx: StatusContext): void {
+  const last = samples[samples.length - 1]
+  if (last && ctx.now - last.at < 1000) return
+  samples.push({
+    at: ctx.now,
+    ratio: contextRatio(ctx.session) ?? 0,
+    cost: ctx.session?.cost ?? 0,
+  })
+  if (samples.length > 30) samples.shift()
+}
+
+export default {
+  segments: {
+    /**
+     * The context window as a bar with a scale: every cell carries the colour of the level it
+     * stands for, and a quarter tick marks the empty half so the bar can be read against
+     * something rather than eyeballed.
+     */
+    bar(ctx: StatusContext, config) {
+      const ratio = contextRatio(ctx.session)
+      if (ratio === undefined) return undefined
+      const width = typeof config.width === "number" ? config.width : 20
+      const filled = Math.round(ratio * width)
+      const runs: Run[] = [{ text: "▕", tone: "border" }]
+      for (let cell = 0; cell < width; cell++) {
+        if (cell < filled) {
+          runs.push({ text: "█", color: gradient((cell + 1) / width) })
+        } else {
+          const tick = cell > 0 && Math.abs(((cell + 1) / width) % 0.25) < 1 / width
+          runs.push({ text: tick ? "┊" : "░", tone: "border" })
+        }
+      }
+      runs.push({ text: "▏", tone: "border" })
+      runs.push({
+        text: ` ${Math.round(ratio * 100)}%`,
+        color: gradient(ratio),
+        bold: ratio >= 0.85,
+      })
+      return { runs }
+    },
+
+    /**
+     * How fast the window is filling, as a figure rather than a picture.
+     *
+     * This was a sparkline. A sparkline redraws its whole shape every second, and a shape moving
+     * in the corner of your eye pulls attention away from what you are reading -- which is the one
+     * thing a statusline must not do. The same information as a rate changes its digits and
+     * nothing else.
+     */
+    filling(ctx: StatusContext) {
+      sample(ctx)
+      const seen = samples.filter((entry) => entry.ratio > 0)
+      const first = seen[0]
+      const last = seen[seen.length - 1]
+      if (!first || !last || last.at === first.at) return undefined
+      const perMinute = ((last.ratio - first.ratio) / (last.at - first.at)) * 60_000 * 100
+      if (Math.abs(perMinute) < 0.05) return undefined
+      // Minutes left at this rate is the figure worth knowing; the rate itself is the input.
+      const headroom = (1 - last.ratio) * 100
+      const minutesLeft = perMinute > 0 ? headroom / perMinute : Number.POSITIVE_INFINITY
+      return {
+        runs: [
+          { text: `+${perMinute.toFixed(1)}%/min`, tone: "muted" as const },
+          ...(Number.isFinite(minutesLeft) && minutesLeft < 90
+            ? [
+                {
+                  text: ` · ${Math.round(minutesLeft)}m left`,
+                  tone: minutesLeft < 15 ? ("warning" as const) : ("muted" as const),
+                },
+              ]
+            : []),
+        ],
+      }
+    },
+
+    /** Spend per minute with a direction. Silent where nobody declared prices. */
+    rate(ctx: StatusContext) {
+      sample(ctx)
+      const session = ctx.session
+      if (!session?.priced || session.cost <= 0) return undefined
+      const first = samples[0]
+      const last = samples[samples.length - 1]
+      if (!first || !last || last.at === first.at) return undefined
+      const perMinute = ((last.cost - first.cost) / (last.at - first.at)) * 60_000
+      if (perMinute < 0.005) return undefined
+      return {
+        runs: [
+          { text: perMinute > 0.5 ? "▲" : "▸", tone: perMinute > 0.5 ? "warning" : "muted" },
+          { text: ` $${perMinute.toFixed(2)}/min`, tone: "muted" },
+        ],
+      }
+    },
+
+    /**
+     * How much of the window is cache rather than fresh input. High is cheap and fast; low means
+     * the session keeps re-sending what it already sent.
+     */
+    cached(ctx: StatusContext) {
+      const tokens = ctx.session?.tokens
+      const total = contextUsed(tokens)
+      if (!tokens || total === 0) return undefined
+      const share = tokens.cache.read / total
+      return {
+        runs: [
+          { text: "▌", tone: share > 0.5 ? "success" : "muted" },
+          { text: `${Math.round(share * 100)}% cached`, tone: "muted" },
+        ],
+      }
+    },
+
+    /** The session's own size, for when a window has quietly filled up with one long turn. */
+    tokens(ctx: StatusContext) {
+      const used = contextUsed(ctx.session?.tokens)
+      return used > 0 ? { text: `${compact(used)} tok`, tone: "muted" as const } : undefined
+    },
+  },
+} satisfies CustomModule