@opencode-cockpit/status 0.3.0

package/types/core/context.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The snapshot a segment sees. Deliberately a plain object rather than the live plugin api: every
+ * built-in is then a pure function of it, which is what makes the line testable without an
+ * OpenCode to draw it in.
+ */
+export interface TokenCounts {
+    input: number;
+    output: number;
+    reasoning: number;
+    cache: {
+        read: number;
+        write: number;
+    };
+}
+export interface SessionSnapshot {
+    id: string;
+    title?: string;
+    /** `retry` carries the attempt and when the next one is due. */
+    status: "idle" | "busy" | "retry";
+    retry?: {
+        attempt: number;
+        message: string;
+        next: number;
+    };
+    model?: {
+        providerID: string;
+        modelID: string;
+        /** Absent for a provider whose context window nobody has declared. */
+        contextLimit?: number;
+    };
+    /** From the last assistant message: what is actually in the window right now. */
+    tokens?: TokenCounts;
+    /**
+     * Summed over the session. Zero for a provider with no declared prices — which is why the cost
+     * segment reports whether prices exist rather than trusting the number.
+     */
+    cost: number;
+    /** False when no model in play has prices, so cost is 0 because nobody said otherwise. */
+    priced: boolean;
+    messages: number;
+    startedAt?: number;
+    diff: {
+        files: number;
+        additions: number;
+        deletions: number;
+    };
+    todo: {
+        total: number;
+        completed: number;
+    };
+}
+export interface ServiceSnapshot {
+    name: string;
+    /** Anything but "connected"/"ready" reads as unhealthy. */
+    status: string;
+}
+export interface StatusContext {
+    now: number;
+    /** OpenCode's current directory and the worktree root it sits in. */
+    directory: string;
+    worktree: string;
+    home: string;
+    branch?: string;
+    defaultBranch?: string;
+    version: string;
+    session?: SessionSnapshot;
+    lsp: ServiceSnapshot[];
+    mcp: ServiceSnapshot[];
+    /** Output of the configured commands, by name. Absent until the first run finishes. */
+    commands: Record<string, string>;
+    /** Terminal width the line has to fit into. */
+    width: number;
+}
+/** Tokens that occupy the context window right now: everything the model reads back. */
+export declare function contextUsed(tokens: TokenCounts | undefined): number;
+export declare function contextRatio(session: SessionSnapshot | undefined): number | undefined;
+export declare function todoRemaining(session: SessionSnapshot | undefined): number;
+export declare function unhealthy(list: readonly ServiceSnapshot[]): ServiceSnapshot[];

package/types/core/custom.d.ts

@@ -0,0 +1,49 @@
+import type { SegmentConfig } from "./config.ts";
+import type { StatusContext } from "./context.ts";
+import type { Run, SegmentDef, Tone } from "./segments.ts";
+/**
+ * Your own segments, written in TypeScript.
+ *
+ * The declarative config covers the usual line and a shell command covers anything with a CLI, but
+ * neither can read the session and decide. A module can: it is handed the same snapshot the
+ * built-ins get, and what it returns is placed, coloured, prioritised and collapsed exactly like
+ * one of them.
+ *
+ * A module default-exports its segments by name:
+ *
+ *   import type { StatusContext } from "@opencode-cockpit/status/segment"
+ *
+ *   export default {
+ *     segments: {
+ *       burn: (ctx: StatusContext) => {
+ *         const mins = (ctx.now - (ctx.session?.startedAt ?? ctx.now)) / 60000
+ *         if (!ctx.session?.priced || mins < 1) return undefined
+ *         return { text: `$${(ctx.session.cost / mins).toFixed(2)}/min`, tone: "warning" }
+ *       },
+ *     },
+ *   }
+ *
+ * and the name is then usable in the config like any built-in: `"segments": ["burn"]`.
+ */
+/** What a module's segment function is handed and what it may return. */
+export type CustomRender = (ctx: StatusContext, config: SegmentConfig) => {
+    text: string;
+    tone?: Tone;
+    color?: string;
+} | {
+    runs: Run[];
+} | string | undefined;
+export interface CustomModule {
+    segments?: Record<string, CustomRender | {
+        render: CustomRender;
+        priority?: number;
+    }>;
+}
+export interface LoadResult {
+    segments: Map<string, SegmentDef>;
+    /** One line per module that could not be loaded, for a toast the user can act on. */
+    errors: string[];
+}
+/** `~/x`, an absolute path, or one relative to the project. */
+export declare function resolveModulePath(path: string, directory: string, home?: string): string;
+export declare function loadCustomSegments(paths: readonly string[], directory: string, importer?: (path: string) => Promise<unknown>): Promise<LoadResult>;

package/types/core/format.d.ts

@@ -0,0 +1,56 @@
+/** Formatting for a line where every column costs something. */
+/** 1234 → "1.2k", 1_200_000 → "1.2M". Whole numbers below 1000 stay as they are. */
+export declare function compact(n: number): string;
+/**
+ * Money, at the precision the amount deserves: cents matter at $0.42, they do not at $124.
+ * Sub-cent spend reads as "<$0.01" rather than "$0.00", which looks like nothing was spent.
+ */
+export declare function money(amount: number, currency?: string): string;
+/** "4s", "3m", "2h 5m" — a statusline has no room for "2 hours, 5 minutes". */
+export declare function duration(ms: number): string;
+/** A percentage with no decimal point, because the last digit never changes a decision. */
+export declare function percent(ratio: number): string;
+/** A fractional bar: "███▌  ". Width is in cells, and the result is always exactly that wide. */
+export declare function bar(ratio: number, width: number): string;
+/**
+ * The path as a person would say it: "" at the worktree root, "src/tui" inside it, "~/other"
+ * elsewhere under home, and the plain path otherwise.
+ */
+export declare function shortPath(directory: string, worktree: string, home: string): string;
+export declare function basename(path: string): string;
+/**
+ * Model ids carry a vendor prefix and a date nobody reads at a glance
+ * ("anthropic/claude-opus-5-20260101" → "claude-opus-5").
+ */
+export declare function shortModel(modelID: string): string;
+/**
+ * Cuts from the left, keeping the end. For a path the tail is what identifies it: "…/src/tui"
+ * says where you are, "/Users/me/very/lo…" does not.
+ */
+export declare function truncateStart(text: string, max: number): string;
+/** Cuts to `max` cells, marking the cut. Never returns more than `max`. */
+export declare function truncate(text: string, max: number): string;
+type Rgb = [number, number, number];
+/**
+ * The colour at `t` (0..1) along a gradient, interpolated rather than bucketed. A bar whose cells
+ * step smoothly from green to red reads as a measurement; one that flips between three colours
+ * reads as three states.
+ */
+export declare function gradient(t: number, stops?: Rgb[]): string;
+/**
+ * "3m42s" while you are watching it, "2d 13h" once you are not.
+ *
+ * Each tier drops the one below as it stops mattering: seconds are worth watching in the first
+ * minute and meaningless after an hour, and "61h48m" is a number nobody converts in their head.
+ */
+export declare function preciseDuration(ms: number): string;
+/**
+ * Filling `{name}` placeholders from a segment's own values.
+ *
+ * This is what a `format` setting runs on. A segment that draws several figures should not also
+ * decide the words between them — "3f +12 -4" suits one line and "+12/-4" another, and neither is
+ * ours to insist on. An unknown placeholder is left as written, so a typo is visible rather than
+ * silently blank.
+ */
+export declare function template(text: string, values: Record<string, string | number>): string;
+export {};

package/types/core/render.d.ts

@@ -0,0 +1,22 @@
+import { type Segment } from "./segments.ts";
+/**
+ * Fitting the line to the terminal.
+ *
+ * Every statusline eventually meets a narrow window. Wrapping turns it into noise and a hard cut
+ * loses whichever segments happen to sit on the right, so instead the lowest-priority segments are
+ * dropped until what is left fits — the things you actually need (how full the context is, whether
+ * something is retrying) survive a 60-column terminal, and the decorations do not.
+ */
+export interface FitResult {
+    segments: Segment[];
+    /** How many were dropped, so the line can say so. */
+    dropped: number;
+}
+export declare function lineWidth(segments: readonly Segment[], separator: string): number;
+export declare function fit(segments: readonly Segment[], width: number, separator: string): FitResult;
+/**
+ * Fitting a column. Height is the constraint rather than width, so segments are not merged onto a
+ * row: each takes one, cut to the column's width, and the lowest-priority ones go when there are
+ * more segments than rows.
+ */
+export declare function fitColumn(segments: readonly Segment[], width: number, maxRows: number): FitResult;

package/types/core/segments.d.ts

@@ -0,0 +1,26 @@
+import { BUILTINS } from "./builtins/index.ts";
+import type { SegmentConfig } from "./config.ts";
+import type { StatusContext } from "./context.ts";
+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 { BUILTINS };
+export declare function runsOf(piece: Piece): Run[];
+export declare function segmentText(segment: Segment): string;
+export declare function segmentWidth(segment: Segment): number;
+/** Cuts a segment to `max` cells, keeping each run's styling up to the cut. */
+export declare function cutSegment(segment: Segment, max: number): Segment;
+export declare function findSegment(type: string): SegmentDef | undefined;
+/**
+ * Builds the line's segments in order, dropping the ones with nothing to say. An unknown type is
+ * dropped too rather than drawn as an error: a stale config should cost you a segment, not a line.
+ */
+export interface BuildOptions {
+    custom?: ReadonlyMap<string, SegmentDef>;
+    /** Icons are on by default; a terminal without the glyphs can switch them off. */
+    icons?: boolean;
+}
+export declare function buildSegments(ctx: StatusContext, configs: SegmentConfig[], options?: BuildOptions | ReadonlyMap<string, SegmentDef>): Segment[];

package/types/core/types.d.ts

@@ -0,0 +1,52 @@
+import type { SegmentConfig } from "./config.ts";
+import type { StatusContext } from "./context.ts";
+/**
+ * A drawn piece of the line. `tone` names a theme colour rather than a literal, so the line
+ * belongs to whatever theme the user runs.
+ */
+export type Tone = "text" | "muted" | "accent" | "success" | "warning" | "error" | "info"
+/** The window's own background and panel colours — what a filled pill puts its text on. */
+ | "background" | "panel" | "border";
+/**
+ * A styled piece of text. A segment is a list of these rather than one string, which is what lets
+ * a single segment carry an icon in one colour, a figure in another, and a bar whose own cells are
+ * coloured by what they represent.
+ */
+export interface Run {
+    text: string;
+    tone?: Tone;
+    /** A literal `#rrggbb`, which wins over `tone`. */
+    color?: string;
+    /** Background, for pills and filled bars. */
+    bg?: string;
+    bgTone?: Tone;
+    bold?: boolean;
+    dim?: boolean;
+}
+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. */
+export type Piece = {
+    text: string;
+    tone?: Tone;
+    color?: string;
+} | {
+    runs: Run[];
+};
+/**
+ * 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
+ * declared prices for reads as "this was free", which is worse than an absent segment.
+ */
+export interface SegmentDef {
+    name: string;
+    /** Used when the config does not override it. */
+    priority: number;
+    /** Shown before the text when icons are on. */
+    icon?: string;
+    render(ctx: StatusContext, config: SegmentConfig): Piece | undefined;
+}

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

@@ -0,0 +1,26 @@
+/** @jsxImportSource @opentui/solid */
+import type { TuiPluginApi, TuiThemeCurrent } from "@opencode-ai/plugin/tui";
+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
+ * rather than literals, so the line belongs to whatever theme the user has chosen — a statusline
+ * in someone else's palette is the first thing that makes a plugin look bolted on.
+ */
+/**
+ * Theme colours are RGBA objects, and OpenTUI wants the object. Stringifying one yields garbage
+ * that the renderer falls back to magenta on, which is how the whole line once came out pink.
+ */
+export type Colour = TuiThemeCurrent["text"];
+export declare function toneColour(theme: TuiThemeCurrent, tone: Tone | undefined): Colour;
+export interface StatusLineProps {
+    api: TuiPluginApi;
+    segments: () => Segment[];
+    separator: string;
+    /** Across the window, or down a column. */
+    stack?: "horizontal" | "vertical";
+    paddingLeft?: number;
+    paddingRight?: number;
+    paddingTop?: number;
+    paddingBottom?: number;
+}
+export declare function StatusLine(props: StatusLineProps): import("solid-js").JSX.Element;

package/types/tui/index.d.ts

@@ -0,0 +1,10 @@
+/** @jsxImportSource @opentui/solid */
+import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui";
+/** Status' TUI half as a factory, so bundles such as `opencode-cockpit` can include it. */
+export declare function createStatusTui({ source }?: {
+    source?: string;
+}): TuiPlugin;
+declare const plugin: TuiPluginModule & {
+    id: string;
+};
+export default plugin;

package/types/tui/state/snapshot.d.ts

@@ -0,0 +1,11 @@
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui";
+import type { SessionSnapshot, StatusContext } from "../../core/context.ts";
+/** The session the interface is showing, when it is showing one. */
+export declare function currentSession(api: TuiPluginApi): string | undefined;
+export declare function sessionSnapshot(api: TuiPluginApi, id: string, now: number): SessionSnapshot;
+export declare function buildContext(api: TuiPluginApi, options: {
+    now: number;
+    width: number;
+    version: string;
+    commands: Record<string, string>;
+}): StatusContext;

package/types/tui/state/store.d.ts

@@ -0,0 +1,28 @@
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui";
+import { type Accessor } from "solid-js";
+import type { StatusConfig } from "../../core/config.ts";
+import type { StatusContext } from "../../core/context.ts";
+/**
+ * Keeps one snapshot of OpenCode's state for every line to read. One memo rather than one per
+ * segment: the whole snapshot is a handful of reads of state already in memory, and recomputing it
+ * once a second costs less than the bookkeeping to avoid it.
+ */
+export interface StatusStore {
+    context: Accessor<StatusContext>;
+    dispose(): void;
+}
+export interface StoreOptions {
+    version: string;
+    /** How often the line recomputes. */
+    tickMs?: number;
+    /** Injected in tests, so no shell runs and no clock is needed. */
+    exec?: (command: string, stdin: string, timeoutMs: number) => Promise<string>;
+    now?: () => number;
+    build: (api: TuiPluginApi, input: {
+        now: number;
+        width: number;
+        version: string;
+        commands: Record<string, string>;
+    }) => StatusContext;
+}
+export declare function createStatusStore(api: TuiPluginApi, config: StatusConfig, options: StoreOptions): StatusStore;