opencode-goal-mode 0.3.0 → 0.3.1

package/ARCHITECTURE.md

@@ -170,7 +170,9 @@ hooks still load.
 `{ tui }` module, mutually exclusive with `{ server }`). It registers a
 `sidebar_content` slot via `api.slots.register({ slots: { sidebar_content } })`
 and renders, in the configured colour (`#FFD700` by default), the short goal
-label plus a `passing/total gates · dirty/ready` line.
+label plus a `passing/total gates · dirty/ready` line. It renders
+unconditionally: when a task is running with no goal set, it shows a muted grey
+`No goal` (`sidebarView` returns `{ hasGoal: false }`) rather than a blank slot.
 
 It is *paired* with the server plugin only through the persisted state file:
 `sidebar-data.js` recomputes the same `stateBaseDir`/`projectKey` path the guard
@@ -182,6 +184,12 @@ error degrades to rendering nothing — it can never break the TUI. The server p
 also emits review-verdict and completion-unlock toasts (`toastOnReview`) so review
 progress is visible even without the banner.
 
+The JSX renderer is verified headlessly with `@opentui/solid`'s `testRender` in
+`tools/visual-test/sidebar-visual.jsx` (`npm run test:visual`, needs Bun + the
+OpenTUI stack): it asserts the rendered text, the exact foreground colours, and
+the bold attribute for goal / "No goal" / ready states. That tool is excluded from
+the npm package and from `node --test`/CI.
+
 ## Configuration
 
 `config.js` merges, in increasing precedence: built-in defaults, environment

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## v0.3.1
+
+- Sidebar: when a task is running but no goal is set, show a clean grey `No goal`
+  (nothing else) instead of a blank/absent banner. New `sidebarMutedColor` option
+  (`GOAL_GUARD_SIDEBAR_MUTED_COLOR`, default `#808080`).
+- `summary.sidebarView` now always returns a model (`{ hasGoal: false }` vs
+  `{ hasGoal: true, … }`) so the sidebar renders unconditionally.
+- Add a headless visual test (`npm run test:visual`, `tools/visual-test/`) that
+  renders the real component with @opentui/solid and asserts text + exact colours
+  + bold attributes across goal / no-goal / ready / custom-colour / truncation /
+  disabled / no-API / resize scenarios. Excluded from the npm package and CI.
+- Hardened the sidebar projection against malformed/partial persisted state.
+
 ## v0.3.0
 
 - Honest benchmarks: add an EXTERNAL corpus of 704 real third-party commands from

package/README.md

@@ -127,13 +127,15 @@ enforcement and writes its state to disk, and an experimental TUI plugin
 
 - **Sidebar goal banner (experimental).** The current goal renders in shining
   yellow in the sidebar (`sidebar_content` slot), with a `passing/total gates ·
-  dirty/ready` status line, and updates as reviews land. It requires a
-  TUI-plugin-capable OpenCode (one exposing `api.slots.register`); on any older
-  runtime it silently no-ops, so it can never break your TUI. Set
-  `sidebarBanner: false` (or `GOAL_GUARD_SIDEBAR_BANNER=0`) to disable, or
-  `sidebarColor` to recolour it. Because no local environment can run OpenCode's
-  TUI runtime, this banner is shipped best-effort and should be verified in your
-  own TUI.
+  dirty/ready` status line, and updates as reviews land. When a task is running
+  but **no goal is set**, it shows a clean grey `No goal` and nothing else. It
+  requires a TUI-plugin-capable OpenCode (one exposing `api.slots.register`); on
+  any older runtime it silently no-ops, so it can never break your TUI. Set
+  `sidebarBanner: false` (or `GOAL_GUARD_SIDEBAR_BANNER=0`) to disable,
+  `sidebarColor` to recolour the goal, or `sidebarMutedColor` for the "No goal"
+  line. It is rendered-and-asserted headlessly by the
+  [visual test](tools/visual-test/README.md) (`npm run test:visual`); still worth
+  a glance in your own TUI.
 - **Toasts.** Review verdicts and completion-unlock events surface as toasts
   (`toastOnReview`), and blocked destructive commands / premature completions
   toast as before (`toastOnBlock`).
@@ -202,6 +204,7 @@ Or via environment variables (`GOAL_GUARD_*`):
 | `toastOnReview` / `GOAL_GUARD_TOAST_ON_REVIEW` | `true` | Toast on each review verdict and when completion unlocks. |
 | `sidebarBanner` / `GOAL_GUARD_SIDEBAR_BANNER` | `true` | Show the experimental yellow goal banner in the TUI sidebar. |
 | `sidebarColor` / `GOAL_GUARD_SIDEBAR_COLOR` | `#FFD700` | Foreground colour of the sidebar goal banner. |
+| `sidebarMutedColor` / `GOAL_GUARD_SIDEBAR_MUTED_COLOR` | `#808080` | Colour of the muted "No goal" line when no goal is set. |
 
 ## Custom tools
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goal-mode",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Strict Goal Mode agents, commands, and guard plugin for OpenCode.",
   "type": "module",
   "engines": {
@@ -31,6 +31,7 @@
     "test:unit": "node --test tests/state.test.mjs tests/gates.test.mjs tests/verdicts.test.mjs tests/config.test.mjs tests/persistence.test.mjs",
     "test:agents": "node --test tests/agents.test.mjs tests/commands.test.mjs",
     "test:install": "node --test tests/install.test.mjs",
+    "test:visual": "bun tools/visual-test/sidebar-visual.jsx",
     "bench": "node benchmarks/run.mjs",
     "bench:external": "node benchmarks/external.mjs",
     "bench:corpus": "node benchmarks/build-external-corpus.mjs",

package/plugins/goal-guard/config.js

@@ -32,6 +32,8 @@ export const DEFAULT_CONFIG = Object.freeze({
   sidebarBanner: true,
   /** Foreground colour (hex) for the sidebar goal banner. */
   sidebarColor: "#FFD700",
+  /** Foreground colour (hex) for the muted "No goal" sidebar line. */
+  sidebarMutedColor: "#808080",
   /** Phrase that, at the start of an assistant message, claims completion. */
   completionMarker: "Goal Completed",
   /** Replacement marker when completion is blocked. */
@@ -68,6 +70,7 @@ function fromEnv(env) {
     GOAL_GUARD_TOAST_ON_REVIEW: ["toastOnReview", coerceBool],
     GOAL_GUARD_SIDEBAR_BANNER: ["sidebarBanner", coerceBool],
     GOAL_GUARD_SIDEBAR_COLOR: ["sidebarColor", (v) => (v == null ? undefined : String(v))],
+    GOAL_GUARD_SIDEBAR_MUTED_COLOR: ["sidebarMutedColor", (v) => (v == null ? undefined : String(v))],
   };
   for (const [key, [field, coerce]] of Object.entries(map)) {
     if (env[key] !== undefined) out[field] = coerce(env[key], DEFAULT_CONFIG[field]);

package/plugins/goal-guard/sidebar-data.js

@@ -13,7 +13,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { stateBaseDir, projectKey } from "./persistence.js";
 import { DEFAULT_CONFIG } from "./config.js";
-import { sidebarView } from "./summary.js";
+import { sidebarView, NO_GOAL } from "./summary.js";
 
 /** Absolute path of the guard's state file for a given worktree. */
 export function sidebarStateFile(worktree, env = process.env) {
@@ -49,8 +49,10 @@ export function pickSession(snapshot, sessionId) {
 }
 
 /**
- * Build the sidebar banner model for a worktree, or null if there is nothing to
- * show. Returns { goal, status, allowed, … } (see summary.sidebarView).
+ * Build the sidebar banner model for a worktree. ALWAYS returns an object so the
+ * sidebar renders unconditionally: `{ hasGoal: false }` when there is no state,
+ * no active session, or no goal (render a muted "No goal"); otherwise
+ * `{ hasGoal: true, goal, status, … }` (see summary.sidebarView).
  *
  * @param {object} opts
  * @param {string} opts.worktree   Project worktree root (same key the guard uses).
@@ -63,9 +65,9 @@ export function readSidebarModel({ worktree, sessionId, config = DEFAULT_CONFIG,
   try {
     snapshot = JSON.parse(readFileSync(sidebarStateFile(worktree, env), "utf8"));
   } catch {
-    return null; // no state yet, or unreadable — show nothing.
+    return NO_GOAL; // no state yet, or unreadable.
   }
   const record = pickSession(snapshot, sessionId);
-  if (!record) return null;
+  if (!record) return NO_GOAL;
   return sidebarView(record, config);
 }

package/plugins/goal-guard/summary.js

@@ -21,21 +21,25 @@ export function shortGoalLabel(state, max = 80) {
   return `${base.slice(0, max - 1).trimEnd()}…`;
 }
 
+/** Sentinel for "a task is running but no goal is set" — the sidebar shows a muted "No goal". */
+export const NO_GOAL = Object.freeze({ hasGoal: false });
+
 /**
- * Compact projection for the TUI sidebar banner: the short goal label, a
- * one-line gate/dirty status, and whether completion is currently allowed.
- * Returns null when there is no active goal worth showing.
+ * Compact projection for the TUI sidebar banner. ALWAYS returns an object so the
+ * sidebar can render unconditionally:
+ *   - `{ hasGoal: false }` when no active goal is set (render a muted "No goal").
+ *   - `{ hasGoal: true, goal, status, … }` when a goal is active (render in colour).
  */
 export function sidebarView(state, config) {
-  if (!state || !state.active) return null;
+  if (!state || !state.active) return NO_GOAL;
   const goal = shortGoalLabel(state);
-  if (!goal) return null;
+  if (!goal) return NO_GOAL;
   const required = requiredGates(state, config);
   const missing = missingGates(state, config);
   const passing = required.length - missing.length;
   const allowed = required.length > 0 && missing.length === 0 && !state.dirty;
   const status = `${passing}/${required.length} gates` + (state.dirty ? " · dirty" : "") + (allowed ? " · ready" : "");
-  return { goal, status, allowed, reviewCycles: state.reviewCycles, passing, required: required.length, dirty: Boolean(state.dirty) };
+  return { hasGoal: true, goal, status, allowed, reviewCycles: state.reviewCycles, passing, required: required.length, dirty: Boolean(state.dirty) };
 }
 
 export function summarizeState(state, config) {

package/plugins/goal-sidebar.js

@@ -28,10 +28,11 @@
  */
 
 import { createSignal, onCleanup, Show } from "solid-js";
-import { sidebarView } from "./goal-guard/summary.js";
+import { sidebarView, NO_GOAL } from "./goal-guard/summary.js";
 import { DEFAULT_CONFIG } from "./goal-guard/config.js";
 
 const DEFAULT_COLOR = "#FFD700"; // shining yellow
+const DEFAULT_MUTED = "#808080"; // clean grey for "No goal"
 const POLL_MS = 1500;
 
 function resolveOptions(options, env) {
@@ -41,7 +42,8 @@ function resolveOptions(options, env) {
   const disabled =
     enabledOpt === false || enabledEnv === "0" || enabledEnv === "false" || enabledEnv === "off";
   const color = options?.sidebarColor || e.GOAL_GUARD_SIDEBAR_COLOR || DEFAULT_COLOR;
-  return { enabled: !disabled, color };
+  const muted = options?.sidebarMutedColor || e.GOAL_GUARD_SIDEBAR_MUTED_COLOR || DEFAULT_MUTED;
+  return { enabled: !disabled, color, muted };
 }
 
 /**
@@ -82,14 +84,14 @@ function pickSession(snapshot, sessionId) {
 }
 
 function readModel(worktree, sessionId) {
-  const snapshot = readSnapshot(worktree);
-  if (!snapshot) return null;
-  const record = pickSession(snapshot, sessionId);
-  if (!record) return null;
   try {
+    const snapshot = readSnapshot(worktree);
+    if (!snapshot) return NO_GOAL;
+    const record = pickSession(snapshot, sessionId);
+    if (!record) return NO_GOAL;
     return sidebarView(record, DEFAULT_CONFIG);
   } catch {
-    return null;
+    return NO_GOAL;
   }
 }
 
@@ -98,7 +100,7 @@ export const id = "goal-mode-sidebar";
 /** @type {import("@opencode-ai/plugin/tui").TuiPlugin} */
 export const tui = async (api, options) => {
   try {
-    const { enabled, color } = resolveOptions(options, typeof process !== "undefined" ? process.env : {});
+    const { enabled, color, muted } = resolveOptions(options, typeof process !== "undefined" ? process.env : {});
     if (!enabled) return;
     if (!api?.slots?.register) return; // runtime without the slot API → no-op.
 
@@ -110,25 +112,26 @@ export const tui = async (api, options) => {
         sidebar_content(_ctx, props) {
           const read = () => {
             try {
-              return readModel(worktree, props?.session_id);
+              return readModel(worktree, props?.session_id) || NO_GOAL;
             } catch {
-              return null;
+              return NO_GOAL;
             }
           };
           const [model, setModel] = createSignal(read());
           const timer = setInterval(() => setModel(read()), POLL_MS);
           onCleanup(() => clearInterval(timer));
+          // Always render: a muted "No goal" when none is set, the goal in colour otherwise.
           return (
-            <Show when={model()}>
-              <box flexDirection="column">
+            <box flexDirection="column">
+              <Show when={model().hasGoal} fallback={<text fg={muted}>No goal</text>}>
                 <text fg={color}>
                   {"◆ "}
                   <b>GOAL</b>
                   {`  ${model().goal}`}
                 </text>
                 <text fg={color}>{model().status}</text>
-              </box>
-            </Show>
+              </Show>
+            </box>
           );
         },
       },