@opencode-cockpit/status 0.3.1 → 0.3.2

package/dist/cli/preview.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env bun
 /**
  * Draw your statusline in this terminal, against sample sessions, without restarting OpenCode.
  *
@@ -10,7 +11,6 @@
  * 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";

package/dist/core/custom.js

@@ -55,8 +55,26 @@ const AUTHORING = "@opencode-cockpit/status/segment";
  * imports still work. Only on failure: a module inside a project that installed the bay never
  * takes this path.
  */
+/**
+ * This file's own authoring module, from a checkout or from a build.
+ *
+ * The specifier is a string argument rather than an import, so the build's `./x.ts` → `./x.js`
+ * rewrite never touched it: published copies asked for a `.ts` that is not beside them and threw,
+ * which took out the whole fallback and with it every module living outside a project. Ask for
+ * both, in the order that keeps a checkout resolving to its source.
+ */
+function authoringModule() {
+  for (const candidate of ["./authoring.ts", "./authoring.js"]) {
+    try {
+      return Bun.resolveSync(candidate, import.meta.dir);
+    } catch {
+      // try the other extension
+    }
+  }
+  throw new Error("cannot find the statusline authoring module beside this one");
+}
 async function importWithAuthoring(full) {
-  const resolved = Bun.resolveSync("./authoring.ts", import.meta.dir);
+  const resolved = authoringModule();
   const source = await Bun.file(full).text();
   const patched = source.replaceAll(AUTHORING, pathToFileURL(resolved).href);
   if (patched === source) throw new Error(`does not import ${AUTHORING}`);

package/dist/core/instructions.js

@@ -0,0 +1,31 @@
+/**
+ * The brief `/statusline` hands to the agent.
+ *
+ * The command draws nothing. Customising a statusline is an editing job — a JSON file the TUI never
+ * names, or a TypeScript module against an api that is written down only on a website — so the
+ * useful thing to put on screen is not a help panel the user then has to act on themselves. It is a
+ * message to the agent already sitting in the session, carrying the facts it cannot look up: which
+ * config file this project actually reads, what is in it right now, and where the taste rules live.
+ *
+ * Plain text rather than a UI also means the same brief works from anywhere the agent can be asked
+ * a question, and can be tested as a string.
+ */
+
+import { BUILTINS } from "./builtins/index.js";
+import { PRESETS } from "./config.js";
+/** The file an edit should go to: the project's if it exists, else the one for every project. */
+export function targetConfig(report) {
+  const project = report.sources[1];
+  const global = report.sources[0];
+  const chosen = project?.found ? project : global ?? project;
+  return {
+    path: chosen?.path ?? "",
+    exists: chosen?.found ?? false
+  };
+}
+export function statuslineBrief(report) {
+  const target = targetConfig(report);
+  const drawing = report.lines.length === 0 ? "nothing — no line is configured" : report.lines.map(line => `${line.surface} (${line.stack}), ${line.segments} segment${line.segments === 1 ? "" : "s"}`).join("; ");
+  const modules = report.modules.listed.length === 0 ? "none" : `${report.modules.listed.join(", ")} — ${report.modules.registered} segment${report.modules.registered === 1 ? "" : "s"} registered`;
+  return ["Help me customise my opencode-cockpit statusline.", "", "## Where it stands", "", `- Config to edit: ${target.path}${target.exists ? "" : " (does not exist yet — create it)"}`, `- Drawing now: ${drawing}`, `- My modules: ${modules}`, ...(report.modules.errors.length > 0 ? ["- Failing to load:", ...report.modules.errors.map(error => `  - ${error}`)] : []), `- Version: ${report.version}`, "", "## What you can change", "", 'The config file holds `{ "statusline": { ... } }`. Two surfaces: `bottom` (a line under the', "prompt) and `sidebar` (a column). A whole line by name with `preset`, then anything written", "beside it wins:", "", ...Object.entries(PRESETS).map(([name, preset]) => `- \`"preset": "${name}"\` — ${preset.about} (${preset.surface})`), "", `Built-in segment names: ${BUILTINS.map(segment => segment.name).join(", ")}.`, 'A segment can also be `{ "type": "...", ... }` with its own settings, or a shell command.', "", "For anything the built-ins do not cover, write a TypeScript module and list it in `modules`:", "it exports `{ segments: { name(ctx, config) { return { runs: [...] } } } }` against", "`@opencode-cockpit/status/segment`, is handed a snapshot rather than OpenCode's api, and is", "called on every repaint so it can keep history. Returning `undefined` hides a segment.", "", "## Before you say it is done", "", "Look at it. Do not edit, restart OpenCode and judge from a sentence:", "", "```sh", "bunx @opencode-cockpit/status preview --watch    # redraws on every save", "bunx @opencode-cockpit/status preview --debug    # mark segments that drew nothing", "bunx @opencode-cockpit/status preview --module <my module> --state full", "```", "", "The design rules are a skill shipped with the package at", "`node_modules/@opencode-cockpit/status/skills/statusline-design/SKILL.md` — read it before", "designing anything, and copy the examples beside it rather than inventing glyphs. The reference", "is https://codestz.github.io/opencode-cockpit/status/.", "", "Ask me what I want it to show before you edit anything."].join("\n");
+}

package/dist/core/report.js

@@ -0,0 +1,54 @@
+/**
+ * What the statusline is actually doing right now, as data.
+ *
+ * The bay's own rule is that a segment with nothing to say says nothing, which is right on screen
+ * and leaves exactly one question unanswerable from the screen itself: is this line quiet because
+ * there is nothing to report, or because the config never arrived? This is the answer — which files
+ * were read, which surfaces are drawing, how many segments each carries, and what a module did when
+ * it failed to load. The `/statusline` command draws it; it lives here because it is a pure
+ * function of the settings, and so can be tested without a terminal.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { globalConfigPath, PROJECT_FILE } from "./config.js";
+export function buildReport(input) {
+  const global = globalConfigPath(input.env ?? process.env);
+  const project = join(input.directory, PROJECT_FILE);
+  return {
+    version: input.version,
+    sources: [global, project].map(path => ({
+      path,
+      found: existsSync(path)
+    })),
+    lines: input.lines.map(line => ({
+      surface: line.surface,
+      stack: line.stack,
+      segments: line.segments.length,
+      maxRows: line.stack === "vertical" ? line.maxRows : undefined
+    })),
+    modules: {
+      listed: [...(input.modules ?? [])],
+      registered: input.registered,
+      errors: [...input.errors]
+    }
+  };
+}
+
+/**
+ * The one sentence a report is worth opening for: whether anything is drawing at all, and if not,
+ * the likeliest reason given what was found.
+ */
+export function reportHeadline(report) {
+  if (report.modules.errors.length > 0) {
+    const count = report.modules.errors.length;
+    return `${count} module${count === 1 ? "" : "s"} failed to load — segments from ${count === 1 ? "it" : "them"} are missing`;
+  }
+  if (report.lines.length === 0) return "Nothing is drawing: no line is configured";
+  if (report.sources.every(source => !source.found)) {
+    return "Drawing the defaults — neither config file exists yet";
+  }
+  const rows = report.lines.reduce((sum, line) => sum + line.segments, 0);
+  const where = [...new Set(report.lines.map(line => line.surface))].join(" and ");
+  return `${rows} segment${rows === 1 ? "" : "s"} across the ${where}`;
+}

package/dist/tui/index.js

@@ -7,7 +7,9 @@ import { createMemo } from "solid-js";
 import pkg from "../../package.json" with { type: "json" };
 import { asSegmentConfig, loadStatusConfig, resolveLines } from "../core/config.js";
 import { loadCustomSegments } from "../core/custom.js";
+import { statuslineBrief } from "../core/instructions.js";
 import { fit, fitColumn } from "../core/render.js";
+import { buildReport } from "../core/report.js";
 import { buildSegments } from "../core/segments.js";
 import { StatusLine } from "./components/statusline.js";
 import { buildContext } from "./state/snapshot.js";
@@ -37,6 +39,7 @@ export function createStatusTui({
 
     // Your own segments, loaded before the first draw so they are never missing from frame one.
     let custom = new Map();
+    const moduleErrors = [];
     if (config.modules?.length) {
       const loaded = await loadCustomSegments(config.modules, directory);
       custom = loaded.segments;
@@ -47,6 +50,7 @@ export function createStatusTui({
        * — a whole session was once spent diagnosing an import that had already explained itself
        * and then disappeared.
        */
+      moduleErrors.push(...loaded.errors);
       for (const error of loaded.errors) {
         api.ui.toast({
           variant: "error",
@@ -101,6 +105,50 @@ export function createStatusTui({
         }
       });
     };
+
+    /**
+     * `/statusline` draws nothing. Customising a line is an editing job in a file the TUI never
+     * names, so the useful thing is not a help panel the user then has to act on themselves — it is
+     * a brief handed to the agent already in the session, carrying what it cannot look up: which
+     * config file this project reads, what is in it now, and what would not load.
+     */
+    api.keymap.registerLayer({
+      commands: [{
+        name: "cockpit.status.customise",
+        title: "Statusline: ask the agent to customise it",
+        category: "Statusline",
+        namespace: "palette",
+        slashName: "statusline",
+        run: () => {
+          const brief = statuslineBrief(buildReport({
+            version: pkg.version,
+            directory,
+            lines,
+            modules: config.modules,
+            registered: custom.size,
+            errors: moduleErrors
+          }));
+          /**
+           * Sent, not left in the prompt. The brief is forty lines; parked in the input it is a
+           * wall of text the user has to scroll past to type their own sentence, and it ends by
+           * asking what they want anyway — so the agent is the right place for it to land.
+           *
+           * On the next tick, because running a slash command clears the prompt it was typed
+           * into: writing during the command itself is wiped a moment later, which looks exactly
+           * like a command that did nothing.
+           */
+          setTimeout(() => {
+            void api.client.tui.appendPrompt({
+              text: brief
+            }).then(() => api.client.tui.submitPrompt()).catch(() => api.ui.toast({
+              variant: "error",
+              title: "Statusline",
+              message: "could not reach the prompt"
+            }));
+          }, 0);
+        }
+      }]
+    });
     const on = surface => lines.filter(spec => spec.surface === surface);
     const bottom = on("bottom");
     const sidebar = on("sidebar");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-cockpit/status",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "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",
@@ -57,7 +57,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@opencode-cockpit/client": "0.3.1",
+    "@opencode-cockpit/client": "0.3.2",
     "@opencode-ai/plugin": "1.18.31"
   },
   "devDependencies": {
@@ -67,6 +67,7 @@
     "solid-js": "1.9.12"
   },
   "bin": {
-    "opencode-statusline": "./dist/cli/preview.js"
+    "opencode-statusline": "./dist/cli/preview.js",
+    "status": "./dist/cli/preview.js"
   }
 }

package/skills/statusline-design/SKILL.md

@@ -36,15 +36,35 @@ look solid", and the two interpretations share no code.
 | **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. |
+| **Bars are solid.** Filled cells `█` coloured by level; the empty track is `█` in **`border`** tone. | `░` reads as floating gaps and `─` reads as `-----`. Both were rejected on sight. Swapping one rejected glyph for another is not iteration. `panel` is the colour of the panel the bar sits on, so a track drawn in it is invisible. |
 | **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. |
+| **No end caps on a bar in a column.** `▕` and `▏` are eighth-blocks whose ink sits hard against one edge of the cell. | An opening cap indents the row by most of a column, and the bar stops lining up with the labels above and below it. Caps are fine on a line, where nothing has to align. |
+| **Print a number once.** A bar and the figure beside it are one row; the same percentage on the row below is a second copy. | In a column of ten rows the repeated figure is the thing the eye catches on. Let the bar be cells and let the labelled row carry the number. |
 | **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 six states, and what each one catches
+
+A design is judged mid-session and ships broken everywhere else. `--state <name>` draws one; with
+no flag the preview draws all six. Every one of these has caught something real:
+
+| State | What it is | What it catches |
+| --- | --- | --- |
+| `fresh` | a session before the first reply: no model, no tokens, no cost | the wall of zeroes, and `0%` against a window nobody has declared |
+| `working` | a few turns in, most of the window served from cache | the ordinary case — and that `cache` dwarfs `in` and `out`, which a layout has to survive |
+| `full` | nearly out of room, a long session | the widest every number gets: `191.6k`, `100%`, four-figure spend. Column widths that only fit `85.2k` shear here |
+| `unpriced` | behind a proxy, nothing declared in the catalogue | segments that invent `$0.00` rather than staying silent |
+| `retrying` | a stalled turn, retry pending | a status that reads "busy" forever, and rows that vanish mid-turn because a streaming message reports zeroes |
+| `empty` | no session at all — what a window shows at start-up | the half of the line that is mounted before anything exists |
+
+Two rules fall out of them: **check `fresh` and `empty` before you call anything done**, because
+they are what a new user sees first; and **size every column against `full`**, not against the
+state you happen to be looking at.
+
 ## The renderer's contract
 
 - One segment draws **one row**, unless it returns an **array** of pieces — then each element is a

package/types/cli/preview.d.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env bun
 /**
  * Draw your statusline in this terminal, against sample sessions, without restarting OpenCode.
  *

package/types/core/instructions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The brief `/statusline` hands to the agent.
+ *
+ * The command draws nothing. Customising a statusline is an editing job — a JSON file the TUI never
+ * names, or a TypeScript module against an api that is written down only on a website — so the
+ * useful thing to put on screen is not a help panel the user then has to act on themselves. It is a
+ * message to the agent already sitting in the session, carrying the facts it cannot look up: which
+ * config file this project actually reads, what is in it right now, and where the taste rules live.
+ *
+ * Plain text rather than a UI also means the same brief works from anywhere the agent can be asked
+ * a question, and can be tested as a string.
+ */
+import type { StatusReport } from "./report.ts";
+/** The file an edit should go to: the project's if it exists, else the one for every project. */
+export declare function targetConfig(report: StatusReport): {
+    path: string;
+    exists: boolean;
+};
+export declare function statuslineBrief(report: StatusReport): string;

package/types/core/report.d.ts

@@ -0,0 +1,50 @@
+/**
+ * What the statusline is actually doing right now, as data.
+ *
+ * The bay's own rule is that a segment with nothing to say says nothing, which is right on screen
+ * and leaves exactly one question unanswerable from the screen itself: is this line quiet because
+ * there is nothing to report, or because the config never arrived? This is the answer — which files
+ * were read, which surfaces are drawing, how many segments each carries, and what a module did when
+ * it failed to load. The `/statusline` command draws it; it lives here because it is a pure
+ * function of the settings, and so can be tested without a terminal.
+ */
+import { type ResolvedLine } from "./config.ts";
+export interface ReportLine {
+    surface: string;
+    stack: string;
+    segments: number;
+    /** Vertical lines only: the cap that decides which rows survive. */
+    maxRows?: number;
+}
+export interface StatusReport {
+    version: string;
+    /** Every config file the settings could have come from, in merge order, and whether it exists. */
+    sources: {
+        path: string;
+        found: boolean;
+    }[];
+    lines: ReportLine[];
+    modules: {
+        /** Paths listed in `modules`, as written. */
+        listed: string[];
+        /** Segments those modules actually registered. */
+        registered: number;
+        /** One per module that would not load, already phrased for a human. */
+        errors: string[];
+    };
+}
+export interface ReportInput {
+    version: string;
+    directory: string;
+    lines: readonly ResolvedLine[];
+    modules?: readonly string[];
+    registered: number;
+    errors: readonly string[];
+    env?: Record<string, string | undefined>;
+}
+export declare function buildReport(input: ReportInput): StatusReport;
+/**
+ * The one sentence a report is worth opening for: whether anything is drawing at all, and if not,
+ * the likeliest reason given what was found.
+ */
+export declare function reportHeadline(report: StatusReport): string;