xonecas.io
64875
Mc

mini-coder / commit 64b0b8b

feat: polish empty-state and input guidance

xonecas2026-04-11 64b0b8b115b7c9a1c234cf3fc486f273b10bb7a5 parent 46959dd

13 files changed

spec.md+2−2
@@ -816,10 +816,10 @@ On launch, mini-coder:
816816 6. Selects the launch mode:
817817 - Interactive TUI when `stdin` and `stdout` are both TTYs and `-p` was not provided.
818818 - Headless one-shot mode otherwise.
819-7. In interactive mode, renders the UI with an empty conversation log and the status bar populated.
819+7. In interactive mode, renders the UI with an empty conversation log, a minimal `mini-coder` empty-state banner (showing the packaged version when available, otherwise a simple dev label), and the status bar populated.
820820 8. Starts a new session only when a prompt is actually submitted (no 0-message sessions in the DB).
821821
822-No banner or splash screen. In headless mode, stdout is reserved for NDJSON event output; in interactive mode, the status bar already shows all the context the user needs.
822+The empty-state banner is only shown while the conversation log has no messages. In headless mode, stdout is reserved for NDJSON event output.
823823
824824 ## User settings persistence
825825
src/headless.test.ts+1−0
@@ -56,6 +56,7 @@ function createTestState(): AppState {
5656 activeTurnPromise: null,
5757 showReasoning: true,
5858 verbose: false,
59+ versionLabel: "dev",
5960 customModels: [],
6061 startupWarnings: [],
6162 };
src/index.test.ts+1−0
@@ -52,6 +52,7 @@ function createTestState(plugins: LoadedPlugin[] = []): AppState {
5252 activeTurnPromise: null,
5353 showReasoning: true,
5454 verbose: false,
55+ versionLabel: "dev",
5556 customModels: [],
5657 startupWarnings: [],
5758 };
src/index.ts+4−0
@@ -72,6 +72,7 @@ import {
7272 readImageTool,
7373 shellTool,
7474 } from "./tools.ts";
75+import { resolveAppVersionLabel } from "./version.ts";
7576
7677 // ---------------------------------------------------------------------------
7778 // Constants
@@ -533,6 +534,8 @@ export interface AppState {
533534 plugins: LoadedPlugin[];
534535 /** Active theme (default + plugin overrides). */
535536 theme: Theme;
537+ /** Version label shown in the empty conversation banner. */
538+ versionLabel: string;
536539 /** Current git state (null if not in a repo). */
537540 git: GitState | null;
538541 /** Optional git state loader override used by tests. */
@@ -622,6 +625,7 @@ export async function init(): Promise<AppState> {
622625 skills: promptContext.skills,
623626 plugins: promptContext.plugins,
624627 theme: promptContext.theme,
628+ versionLabel: resolveAppVersionLabel(),
625629 git: promptContext.git,
626630 providers,
627631 oauthCredentials,
src/ui.test.ts+67−4
@@ -2,7 +2,7 @@ import { afterEach, describe, expect, test } from "bun:test";
22 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
33 import { tmpdir } from "node:os";
44 import { join } from "node:path";
5-import { measureContentHeight, VStack } from "@cel-tui/core";
5+import { cel, MockTerminal, measureContentHeight, VStack } from "@cel-tui/core";
66 import type { ContainerNode, Node } from "@cel-tui/types";
77 import type { AssistantMessage, Model } from "@mariozechner/pi-ai";
88 import {
@@ -150,6 +150,38 @@ function createDeferred<T = void>() {
150150 return { promise, resolve, reject };
151151 }
152152
153+async function waitForCelRender(): Promise<void> {
154+ await new Promise((resolve) => setTimeout(resolve, 10));
155+}
156+
157+async function renderLayoutRows(
158+ node: Node,
159+ cols = 40,
160+ rows = 16,
161+): Promise<string[]> {
162+ const terminal = new MockTerminal(cols, rows);
163+ cel.init(terminal);
164+ cel.viewport(() => VStack({ width: cols, height: rows }, [node]));
165+ await waitForCelRender();
166+
167+ const buffer = cel._getBuffer();
168+ if (!buffer) {
169+ throw new Error("Expected cel-tui to produce a render buffer");
170+ }
171+
172+ const snapshot: string[] = [];
173+ for (let y = 0; y < rows; y++) {
174+ let text = "";
175+ for (let x = 0; x < cols; x++) {
176+ text += buffer.get(x, y).char;
177+ }
178+ snapshot.push(text);
179+ }
180+
181+ cel.stop();
182+ return snapshot;
183+}
184+
153185 const tempDirs: string[] = [];
154186
155187 function createTempDir(): string {
@@ -192,6 +224,7 @@ function createTestState(): AppState {
192224 activeTurnPromise: null,
193225 showReasoning: DEFAULT_SHOW_REASONING,
194226 verbose: DEFAULT_VERBOSE,
227+ versionLabel: "dev",
195228 customModels: [],
196229 startupWarnings: [],
197230 };
@@ -476,15 +509,26 @@ describe("ui rendering", () => {
476509 }
477510 });
478511
479- test("empty conversation log renders no splash banner", () => {
512+ test("empty conversation log renders a minimal app banner", () => {
480513 const faux = registerFauxProvider();
481514 const withoutModel = createTestState();
482515 const withModel = createTestState();
483516 withModel.model = faux.getModel();
484517
485518 try {
486- expect(buildConversationLog(withoutModel)).toEqual([]);
487- expect(buildConversationLog(withModel)).toEqual([]);
519+ const withoutModelText = collectText({
520+ type: "vstack",
521+ props: {},
522+ children: buildConversationLog(withoutModel),
523+ });
524+ const withModelText = collectText({
525+ type: "vstack",
526+ props: {},
527+ children: buildConversationLog(withModel),
528+ });
529+
530+ expect(withoutModelText).toEqual(["mini-coder", "dev"]);
531+ expect(withModelText).toEqual(["mini-coder", "dev"]);
488532 } finally {
489533 faux.unregister();
490534 withoutModel.db.close();
@@ -492,6 +536,25 @@ describe("ui rendering", () => {
492536 }
493537 });
494538
539+ test("empty conversation log centers the banner vertically above the input area", async () => {
540+ const state = createTestState();
541+
542+ try {
543+ const rows = await renderLayoutRows(
544+ renderBaseLayout(state, 40, createInputController(state)),
545+ 40,
546+ 16,
547+ );
548+ const bannerRow = rows.findIndex((row) => row.includes("mini-coder"));
549+ const dividerRow = rows.findIndex((row) => row.includes("────"));
550+
551+ expect(bannerRow).toBe(5);
552+ expect(dividerRow).toBe(12);
553+ } finally {
554+ state.db.close();
555+ }
556+ });
557+
495558 test("first user message creates the session lazily", async () => {
496559 const faux = registerFauxProvider();
497560 const state = createTestState();
src/ui.ts+1−0
@@ -573,6 +573,7 @@ function renderConversationLog(state: AppState, width: number): Node {
573573 gap: CONVERSATION_GAP,
574574 overflow: "scroll",
575575 scrollbar: true,
576+ justifyContent: state.messages.length === 0 ? "center" : undefined,
576577 scrollOffset: stickToBottom ? Infinity : scrollOffset,
577578 onScroll: (offset, maxOffset) => {
578579 const wasStickToBottom = stickToBottom;
src/ui/commands.test.ts+1−0
@@ -91,6 +91,7 @@ function createTestState(): AppState {
9191 activeTurnPromise: null,
9292 showReasoning: true,
9393 verbose: false,
94+ versionLabel: "dev",
9495 customModels: [],
9596 startupWarnings: [],
9697 };
src/ui/conversation.ts+37−3
@@ -24,6 +24,7 @@ import type {
2424 import type { AppState } from "../index.ts";
2525 import type { UiMessage } from "../session.ts";
2626 import type { Theme } from "../theme.ts";
27+import { APP_NAME, DEV_VERSION_LABEL } from "../version.ts";
2728
2829 /** Single blank-line gap used between conversation-level blocks. */
2930 export const CONVERSATION_GAP = 1;
@@ -101,6 +102,13 @@ interface AssistantRenderState {
101102
102103 type ConversationMessage = AppState["messages"][number];
103104
105+type ConversationLogState = Pick<
106+ AppState,
107+ "messages" | "showReasoning" | "verbose" | "theme"
108+> & {
109+ versionLabel?: AppState["versionLabel"];
110+};
111+
104112 type ToolCallRenderInfo = {
105113 name: string;
106114 args: Record<string, unknown>;
@@ -926,6 +934,23 @@ function renderUiMessage(msg: UiMessage, theme: Theme): Node {
926934 ]);
927935 }
928936
937+function renderEmptyConversationBanner(
938+ theme: Theme,
939+ versionLabel: string,
940+): Node {
941+ return HStack({ justifyContent: "center" }, [
942+ VStack({ padding: { x: 1 } }, [
943+ Text(APP_NAME, {
944+ bold: true,
945+ fgColor: theme.accentText,
946+ }),
947+ Text(versionLabel, {
948+ fgColor: theme.mutedText,
949+ }),
950+ ]),
951+ ]);
952+}
953+
929954 function pushConversationNode(nodes: Node[], node: Node | null): void {
930955 if (!node) {
931956 return;
@@ -1006,7 +1031,7 @@ function cacheToolCallArgs(messages: readonly ConversationMessage[]): void {
10061031 }
10071032
10081033 function canReuseCommittedConversationCache(
1009- state: Pick<AppState, "messages" | "showReasoning" | "verbose" | "theme">,
1034+ state: ConversationLogState,
10101035 startIndex: number,
10111036 previewWidth: number,
10121037 ): boolean {
@@ -1022,7 +1047,7 @@ function canReuseCommittedConversationCache(
10221047 }
10231048
10241049 function cacheCommittedConversation(
1025- state: Pick<AppState, "messages" | "showReasoning" | "verbose" | "theme">,
1050+ state: ConversationLogState,
10261051 renderOpts: ConversationRenderOpts,
10271052 startIndex: number,
10281053 ): void {
@@ -1077,7 +1102,7 @@ function hasStreamingTail(streaming: StreamingConversationState): boolean {
10771102 * @returns The rendered conversation log nodes.
10781103 */
10791104 export function buildConversationLogNodes(
1080- state: Pick<AppState, "messages" | "showReasoning" | "verbose" | "theme">,
1105+ state: ConversationLogState,
10811106 streaming: StreamingConversationState,
10821107 startIndex = 0,
10831108 previewWidth = DEFAULT_TOOL_PREVIEW_WIDTH,
@@ -1089,6 +1114,15 @@ export function buildConversationLogNodes(
10891114 previewWidth,
10901115 };
10911116
1117+ if (state.messages.length === 0 && !hasStreamingTail(streaming)) {
1118+ return [
1119+ renderEmptyConversationBanner(
1120+ state.theme,
1121+ state.versionLabel ?? DEV_VERSION_LABEL,
1122+ ),
1123+ ];
1124+ }
1125+
10921126 cacheCommittedConversation(state, renderOpts, startIndex);
10931127
10941128 if (!hasStreamingTail(streaming)) {
src/ui/input.test.ts+5−1
@@ -53,7 +53,11 @@ describe("ui/input", () => {
5353 if (!placeholder || placeholder.type !== "text") {
5454 throw new Error("Expected a text placeholder");
5555 }
56- expect(placeholder.content).toBe("message…");
56+ expect(placeholder.content).toBe(
57+ "`Ctrl+R` for input history, `/` + `Tab` for interactive menu, or type a message…",
58+ );
59+ expect(placeholder.props.fgColor).toBe(DEFAULT_THEME.mutedText);
60+ expect(placeholder.props.italic).toBe(true);
5761 });
5862
5963 test("autocompleteInputPath completes the last file path token", () => {
src/ui/input.ts+7−1
@@ -10,6 +10,9 @@ import { Text, TextInput } from "@cel-tui/core";
1010 import type { Node } from "@cel-tui/types";
1111 import type { Theme } from "../theme.ts";
1212
13+const INPUT_PLACEHOLDER =
14+ "`Ctrl+R` for input history, `/` + `Tab` for interactive menu, or type a message…";
15+
1316 /** Stable callbacks for the controlled TextInput. */
1417 export interface InputController {
1518 /** Update the controlled input value and re-render. */
@@ -129,7 +132,10 @@ export function renderInputArea(
129132 padding: { x: 1 },
130133 value,
131134 onChange: controller.onChange,
132- placeholder: Text("message…", { fgColor: theme.mutedText }),
135+ placeholder: Text(INPUT_PLACEHOLDER, {
136+ fgColor: theme.mutedText,
137+ italic: true,
138+ }),
133139 focused,
134140 onFocus: controller.onFocus,
135141 onBlur: controller.onBlur,
src/ui/status.test.ts+1−0
@@ -103,6 +103,7 @@ function createTestState(): AppState {
103103 activeTurnPromise: null,
104104 showReasoning: DEFAULT_SHOW_REASONING,
105105 verbose: DEFAULT_VERBOSE,
106+ versionLabel: "dev",
106107 customModels: [],
107108 startupWarnings: [],
108109 };
src/version.test.ts+49−0
@@ -0,0 +1,49 @@
1+import { afterEach, expect, test } from "bun:test";
2+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
3+import { tmpdir } from "node:os";
4+import { join } from "node:path";
5+import { DEV_VERSION_LABEL, resolveAppVersionLabel } from "./version.ts";
6+
7+const tempDirs: string[] = [];
8+
9+function createTempDir(): string {
10+ const dir = mkdtempSync(join(tmpdir(), "mc-version-test-"));
11+ tempDirs.push(dir);
12+ return dir;
13+}
14+
15+afterEach(() => {
16+ for (const dir of tempDirs.splice(0)) {
17+ rmSync(dir, { recursive: true, force: true });
18+ }
19+});
20+
21+test("resolveAppVersionLabel returns the packaged version when no repo metadata is present", () => {
22+ const root = createTempDir();
23+ writeFileSync(
24+ join(root, "package.json"),
25+ JSON.stringify({ name: "mini-coder", version: "1.2.3" }),
26+ "utf-8",
27+ );
28+
29+ expect(resolveAppVersionLabel(root)).toBe("v1.2.3");
30+});
31+
32+test("resolveAppVersionLabel falls back to the dev label inside a git checkout", () => {
33+ const root = createTempDir();
34+ writeFileSync(
35+ join(root, "package.json"),
36+ JSON.stringify({ name: "mini-coder", version: "1.2.3" }),
37+ "utf-8",
38+ );
39+ mkdirSync(join(root, ".git"));
40+
41+ expect(resolveAppVersionLabel(root)).toBe(DEV_VERSION_LABEL);
42+});
43+
44+test("resolveAppVersionLabel falls back to the dev label when package metadata is unreadable", () => {
45+ const root = createTempDir();
46+ writeFileSync(join(root, "package.json"), "{not json", "utf-8");
47+
48+ expect(resolveAppVersionLabel(root)).toBe(DEV_VERSION_LABEL);
49+});
src/version.ts+48−0
@@ -0,0 +1,48 @@
1+/**
2+ * Version helpers for the interactive empty-state banner.
3+ *
4+ * @module
5+ */
6+
7+import { existsSync, readFileSync } from "node:fs";
8+import { join } from "node:path";
9+
10+/** App name shown in the empty conversation banner. */
11+export const APP_NAME = "mini-coder";
12+
13+/** Fallback label used when running from a local checkout instead of a packaged install. */
14+export const DEV_VERSION_LABEL = "dev";
15+
16+/**
17+ * Resolve the version label shown in the empty conversation banner.
18+ *
19+ * Packaged installs read their version from the colocated `package.json`.
20+ * Local checkouts fall back to a simple `dev` label so banner metadata never
21+ * risks interfering with normal startup.
22+ *
23+ * @param appRoot - App root containing `package.json`.
24+ * @returns A display label such as `v0.5.1` or `dev`.
25+ */
26+export function resolveAppVersionLabel(
27+ appRoot = join(import.meta.dir, ".."),
28+): string {
29+ if (existsSync(join(appRoot, ".git"))) {
30+ return DEV_VERSION_LABEL;
31+ }
32+
33+ const packageJsonPath = join(appRoot, "package.json");
34+ if (!existsSync(packageJsonPath)) {
35+ return DEV_VERSION_LABEL;
36+ }
37+
38+ try {
39+ const parsed = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as {
40+ version?: unknown;
41+ };
42+ return typeof parsed.version === "string" && parsed.version !== ""
43+ ? `v${parsed.version}`
44+ : DEV_VERSION_LABEL;
45+ } catch {
46+ return DEV_VERSION_LABEL;
47+ }
48+}