opencode-goal-mode 0.3.5 → 0.3.6

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## v0.3.6
+
+- **FIX: the sidebar never loaded.** TUI plugins are loaded from
+  `~/.config/opencode/tui.json` — NOT the `plugins/` dir (that is server plugins
+  only). The installer never created tui.json, so OpenCode never loaded the
+  sidebar (it only showed the session title + context). The installer now
+  registers the sidebar in `tui.json` (`plugin: ["opencode-goal-mode"]`,
+  merge-safe), and the package `main` points at the TUI plugin so OpenCode loads
+  it with its `@opentui/solid` runtime. Confirmed OpenCode reads tui.json.
+- **Sidebar behaviour, as requested:** under the sidebar's content/"context"
+  area it now shows the goal with generated status text, colour-coded by
+  lifecycle: **yellow** while the goal is running, **red** when it is done (all
+  required gates pass, tree clean), and **grey "No goal available"** when a task
+  is running with no goal set. New `sidebarDoneColor` option
+  (`GOAL_GUARD_SIDEBAR_DONE_COLOR`, default `#FF5555`).
+- `summary.sidebarView` now returns `{ state: "none"|"running"|"done", goal,
+  detail }`; the headless visual test renders and asserts all three states (text
+  + exact colours), 18/18.
+
 ## v0.3.5
 
 - Verified the package against the **current** OpenCode plugin API

package/README.md

@@ -18,6 +18,10 @@ npm install -g opencode-goal-mode && opencode-goal-mode-install --global
 
 ![OpenCode Goal Mode sidebar banner](docs/sidebar-demo.svg)
 
+<sub>↑ Illustrative mockup of the **experimental** sidebar banner. The enforcement
+core (guard + agents) is the verified product; the TUI sidebar is opt-in and its
+live render depends on your OpenCode build — see [TUI integration](#tui-integration).</sub>
+
 **[Quick start](#quick-start) · [Install](#install) · [Why it's different](#why-its-different) · [Benchmarks](#benchmarks-honest-edition) · [TUI integration](#tui-integration) · [Configuration](#configuration) · [Releasing](#releasing) · [Architecture](ARCHITECTURE.md)**
 
 ## Quick start
@@ -172,24 +176,31 @@ Goal Mode is a **plugin pair**: the server-side `goal-guard` plugin owns
 enforcement and writes its state to disk, and an experimental TUI plugin
 (`plugins/goal-sidebar.js`) reads that same state to render a live banner.
 
-- **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. When a task is running
-  but **no goal is set**, it shows a clean grey `No goal`. Set
-  `sidebarBanner: false` (or `GOAL_GUARD_SIDEBAR_BANNER=0`) to disable,
-  `sidebarColor` to recolour the goal, or `sidebarMutedColor` for the "No goal"
-  line.
-
-  **Verification status, honestly:** the component is rendered and asserted
-  (text + exact colours) by a real headless OpenTUI renderer in the
-  [visual test](tools/visual-test/README.md) (`npm run test:visual`, 17/17), and
-  OpenCode discovers and boots it as a plugin without error. It needs a recent
-  OpenCode that mounts file-based TUI plugins into the `sidebar_content` slot and
-  provides the `@opentui/solid` runtime; on a build without that, it simply does
-  not appear (it never errors or breaks the TUI — the enforcement core is a
-  separate server plugin and is unaffected). The banner appears in a **session**
-  view, not the home screen. If it doesn't show, that's the TUI-plugin runtime,
-  not Goal Mode's enforcement.
+- **Sidebar goal banner.** In the sidebar's content area, under the session
+  title/context, it shows the current goal with generated status text, colour-coded
+  by lifecycle:
+  - **yellow** — a goal is set and running (`◆ GOAL …` + `in progress · N/M gates`);
+  - **red** — the goal is done (all required gates pass, tree clean: `✓ GOAL …` +
+    `completed · N/M gates passed · K review cycles`);
+  - **grey** — a task is running with no goal set (`No goal available`).
+
+  Toggle/recolour with `sidebarBanner`, `sidebarColor` (running), `sidebarDoneColor`
+  (done), `sidebarMutedColor` (no goal), or the `GOAL_GUARD_SIDEBAR_*` env vars.
+
+  **How it loads — important.** TUI plugins are **not** loaded from the `plugins/`
+  dir; OpenCode loads them from `~/.config/opencode/tui.json`. The installer writes
+  that for you (merge-safe):
+
+  ```json
+  { "$schema": "https://opencode.ai/tui.json", "plugin": ["opencode-goal-mode"] }
+  ```
+
+  Restart OpenCode after install so it picks up the TUI plugin (it resolves the
+  package and provides the `@opentui/solid` runtime). The banner appears in a
+  **session** view (not the home screen). The three states are rendered and
+  asserted — text + exact colours — by a real headless OpenTUI renderer in the
+  [visual test](tools/visual-test/README.md) (`npm run test:visual`, 18/18). The
+  enforcement core is a separate server plugin and works regardless of the sidebar.
 - **Toasts.** Review verdicts and completion-unlock events surface as toasts
   (`toastOnReview`), and blocked destructive commands / premature completions
   toast as before (`toastOnBlock`).
@@ -270,8 +281,9 @@ Or via environment variables (`GOAL_GUARD_*`):
 | `toastOnBlock` / `GOAL_GUARD_TOAST_ON_BLOCK` | `true` | Toast when something is blocked. |
 | `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. |
+| `sidebarColor` / `GOAL_GUARD_SIDEBAR_COLOR` | `#FFD700` | Colour of a **running** goal in the sidebar (yellow). |
+| `sidebarDoneColor` / `GOAL_GUARD_SIDEBAR_DONE_COLOR` | `#FF5555` | Colour of a **done** goal in the sidebar (red). |
+| `sidebarMutedColor` / `GOAL_GUARD_SIDEBAR_MUTED_COLOR` | `#808080` | Colour of the "No goal available" line (grey). |
 
 ## Custom tools
 

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "opencode-goal-mode",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Strict Goal Mode agents, commands, and guard plugin for OpenCode.",
   "type": "module",
+  "main": "plugins/goal-sidebar.js",
   "engines": {
     "node": ">=20.11"
   },

package/plugins/goal-guard/config.js

@@ -32,7 +32,9 @@ 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. */
+  /** Foreground colour (hex) for a completed goal in the sidebar (running → done turns yellow → red). */
+  sidebarDoneColor: "#FF5555",
+  /** Foreground colour (hex) for the muted "No goal available" sidebar line. */
   sidebarMutedColor: "#808080",
   /** Phrase that, at the start of an assistant message, claims completion. */
   completionMarker: "Goal Completed",
@@ -70,6 +72,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_DONE_COLOR: ["sidebarDoneColor", (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)) {

package/plugins/goal-guard/summary.js

@@ -21,14 +21,18 @@ 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 });
+/** Sentinel for "a task is running but no goal is set" — the sidebar shows a muted "No goal available". */
+export const NO_GOAL = Object.freeze({ state: "none", goal: "", detail: "" });
 
 /**
- * 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).
+ * Compact projection for the TUI sidebar banner. ALWAYS returns an object with a
+ * three-way `state` so the sidebar renders unconditionally:
+ *   - `state: "none"`    → no active goal: grey "No goal available".
+ *   - `state: "running"` → goal in progress: yellow, with a generated status line.
+ *   - `state: "done"`    → goal complete (all required gates pass, tree clean):
+ *                           red, with a generated completion line.
+ * `goal` is the short goal label; `detail` is generated descriptive text derived
+ * from the current goal's gate/cycle/dirty state.
  */
 export function sidebarView(state, config) {
   if (!state || !state.active) return NO_GOAL;
@@ -37,9 +41,30 @@ export function sidebarView(state, config) {
   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 { hasGoal: true, goal, status, allowed, reviewCycles: state.reviewCycles, passing, required: required.length, dirty: Boolean(state.dirty) };
+  const cycles = Number(state.reviewCycles) || 0;
+  const done = required.length > 0 && missing.length === 0 && !state.dirty;
+  if (done) {
+    return {
+      state: "done",
+      goal,
+      detail: `completed · ${passing}/${required.length} gates passed · ${cycles} review cycle${cycles === 1 ? "" : "s"}`,
+      passing,
+      required: required.length,
+      reviewCycles: cycles,
+    };
+  }
+  const bits = [`${passing}/${required.length} gates`];
+  if (state.dirty) bits.push("changes pending");
+  if (cycles) bits.push(`cycle ${cycles}`);
+  return {
+    state: "running",
+    goal,
+    detail: `in progress · ${bits.join(" · ")}`,
+    passing,
+    required: required.length,
+    reviewCycles: cycles,
+    dirty: Boolean(state.dirty),
+  };
 }
 
 export function summarizeState(state, config) {

package/plugins/goal-sidebar.js

@@ -1,38 +1,37 @@
 /** @jsxImportSource @opentui/solid */
 /**
- * Goal Mode — experimental TUI sidebar banner.
+ * Goal Mode — TUI sidebar goal banner.
  *
- * EXPERIMENTAL. This is a TUI plugin module (the companion to the server-side
- * goal-guard plugin). It renders the current goal as a short, shining-yellow
- * banner in the OpenCode sidebar, with a compact `passing/total gates ·
- * dirty/ready` status line, and updates as reviews land.
+ * This is a TUI plugin module (companion to the server-side goal-guard plugin).
+ * It renders, in the sidebar's content area, the current goal with generated
+ * status text and a colour that tracks the goal's lifecycle:
+ *   - RUNNING (goal set, in progress)        → yellow
+ *   - DONE    (all required gates pass, clean) → red
+ *   - NONE    (a task is running, no goal set) → grey "No goal available"
  *
- * It only does anything inside a TUI-plugin-capable OpenCode (one exposing
- * `api.slots.register`). On any older runtime, missing API, or render error it
- * silently no-ops — it can never break your TUI.
+ * IMPORTANT — how OpenCode loads this: TUI plugins are NOT loaded from the
+ * regular `plugin` array / plugins dir (that is server plugins). They are listed
+ * in `~/.config/opencode/tui.json`:
+ *     { "$schema": "https://opencode.ai/tui.json", "plugin": ["opencode-goal-mode"] }
+ * The installer writes that automatically. OpenCode then loads this module
+ * (the package `main`) and provides the `@opentui/solid` + `solid-js` runtime
+ * (declared here as peer deps), so its slot shares OpenCode's renderer.
  *
- * Pairing: it reads the SAME on-disk snapshot the goal-guard server plugin
- * writes (see goal-guard/persistence.js), so the two stay in sync with no extra
- * IPC. The pure projection (`summary.sidebarView`) is shared with the server
- * plugin and unit-tested via goal-guard/sidebar-data.js; only the file read and
- * state-path computation are reimplemented here.
- *
- * Runtime constraints (mirrored from working OpenCode TUI plugins):
- *  - TUI plugin modules export `export default { id, tui }`.
- *  - The Bun TUI plugin runtime does NOT support top-level ESM imports of Node
- *    built-ins, so `node:fs`/`node:path`/`node:os`/`node:crypto` are `require()`d
- *    lazily inside functions. Top-level imports of regular packages (solid-js)
- *    and of our Node-built-in-free local modules are fine.
- *  - This file uses Solid/opentui JSX and is loaded only by OpenCode's (Bun) TUI
- *    runtime, which transpiles it; it is never imported by the Node test suite.
+ * Runtime constraints (from working OpenCode TUI plugins):
+ *  - the module exports a single `export default { id, tui }`;
+ *  - the Bun TUI runtime does not support top-level ESM imports of Node built-ins,
+ *    so node:fs/path/os/crypto are require()d lazily inside functions;
+ *  - it is never imported by the Node test suite (the pure projection it uses,
+ *    summary.sidebarView, is tested via goal-guard/sidebar-data.js).
  */
 
 import { createSignal, onCleanup, Show } from "solid-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 DEFAULT_COLOR = "#FFD700"; // shining yellow — running
+const DEFAULT_DONE = "#FF5555"; // red — completed
+const DEFAULT_MUTED = "#808080"; // grey — no goal
 const POLL_MS = 1500;
 
 function resolveOptions(options, env) {
@@ -41,16 +40,15 @@ function resolveOptions(options, env) {
   const enabledEnv = e.GOAL_GUARD_SIDEBAR_BANNER;
   const disabled =
     enabledOpt === false || enabledEnv === "0" || enabledEnv === "false" || enabledEnv === "off";
-  const color = options?.sidebarColor || e.GOAL_GUARD_SIDEBAR_COLOR || DEFAULT_COLOR;
-  const muted = options?.sidebarMutedColor || e.GOAL_GUARD_SIDEBAR_MUTED_COLOR || DEFAULT_MUTED;
-  return { enabled: !disabled, color, muted };
+  return {
+    enabled: !disabled,
+    color: options?.sidebarColor || e.GOAL_GUARD_SIDEBAR_COLOR || DEFAULT_COLOR,
+    doneColor: options?.sidebarDoneColor || e.GOAL_GUARD_SIDEBAR_DONE_COLOR || DEFAULT_DONE,
+    muted: options?.sidebarMutedColor || e.GOAL_GUARD_SIDEBAR_MUTED_COLOR || DEFAULT_MUTED,
+  };
 }
 
-/**
- * Read the guard's persisted snapshot for a worktree. The state-path logic is
- * kept identical to goal-guard/persistence.js (stateBaseDir + projectKey); node
- * built-ins are required lazily to satisfy the TUI runtime.
- */
+/** Read the guard's persisted snapshot for a worktree (path logic mirrors persistence.js). */
 function readSnapshot(worktree) {
   try {
     const fs = require("node:fs");
@@ -100,7 +98,7 @@ const id = "goal-mode-sidebar";
 /** @type {import("@opencode-ai/plugin/tui").TuiPlugin} */
 const tui = async (api, options) => {
   try {
-    const { enabled, color, muted } = resolveOptions(options, typeof process !== "undefined" ? process.env : {});
+    const { enabled, color, doneColor, muted } = resolveOptions(options, typeof process !== "undefined" ? process.env : {});
     if (!enabled) return;
     if (!api?.slots?.register) return; // runtime without the slot API → no-op.
 
@@ -120,16 +118,21 @@ const tui = async (api, options) => {
           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.
+          const fg = () => (model().state === "done" ? doneColor : color);
+          // Always render: grey "No goal available" when none, else the goal in
+          // yellow (running) / red (done) with generated status text.
           return (
-            <box flexDirection="column">
-              <Show when={model().hasGoal} fallback={<text fg={muted}>No goal</text>}>
-                <text fg={color}>
-                  {"◆ "}
+            <box flexDirection="column" paddingTop={1}>
+              <Show
+                when={model().state !== "none"}
+                fallback={<text fg={muted}>No goal available</text>}
+              >
+                <text fg={fg()}>
+                  {model().state === "done" ? "✓ " : "◆ "}
                   <b>GOAL</b>
                   {`  ${model().goal}`}
                 </text>
-                <text fg={color}>{model().status}</text>
+                <text fg={fg()}>{model().detail}</text>
               </Show>
             </box>
           );

package/scripts/install.mjs

@@ -125,6 +125,36 @@ function loadManifest() {
   }
 }
 
+/**
+ * Register (or remove) the TUI sidebar plugin in `<target>/tui.json`.
+ *
+ * TUI plugins are NOT loaded from the `plugins/` dir (that path is for server
+ * plugins); OpenCode loads them only from tui.json. We reference the published
+ * npm package by name so OpenCode resolves it with its `@opentui/solid` runtime.
+ * Merge-safe: preserves any existing entries and only touches our own.
+ */
+const TUI_PLUGIN_SPEC = pkg.name;
+function ensureTuiPlugin(remove = false) {
+  const tuiPath = join(target, "tui.json");
+  let data = { $schema: "https://opencode.ai/tui.json", plugin: [] };
+  try {
+    const existing = JSON.parse(readFileSync(tuiPath, "utf8"));
+    if (existing && typeof existing === "object") data = existing;
+  } catch {
+    /* missing or invalid → start fresh */
+  }
+  if (!Array.isArray(data.plugin)) data.plugin = [];
+  const has = data.plugin.includes(TUI_PLUGIN_SPEC);
+  if (remove ? !has : has) return false;
+  data.plugin = remove ? data.plugin.filter((p) => p !== TUI_PLUGIN_SPEC) : [...data.plugin, TUI_PLUGIN_SPEC];
+  if (!data.$schema) data.$schema = "https://opencode.ai/tui.json";
+  if (!values["dry-run"]) {
+    mkdirSync(target, { recursive: true });
+    writeFileSync(tuiPath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+  }
+  return true;
+}
+
 // ---------------------------------------------------------------------------
 // Uninstall
 // ---------------------------------------------------------------------------
@@ -144,7 +174,9 @@ if (values.uninstall) {
     }
   }
   if (!values["dry-run"] && existsSync(manifestPath)) rmSync(manifestPath, { force: true });
+  const tuiRemoved = ensureTuiPlugin(true);
   if (!values["dry-run"]) pruneEmptyDirs(target, Object.keys(manifest.files));
+  if (tuiRemoved) console.log(`${values["dry-run"] ? "Would remove" : "Removed"} the sidebar entry from ${join(target, "tui.json")}`);
   const verb = values["dry-run"] ? "Would remove" : "Removed";
   console.log(`${verb} ${removed.length} Goal Mode files from ${target}.`);
   if (kept.length) {
@@ -234,9 +266,12 @@ if (!values["dry-run"]) {
   writeFileSync(manifestPath, JSON.stringify({ version: pkg.version, files: newManifestFiles }, null, 2), "utf8");
 }
 
+const tuiAdded = ensureTuiPlugin(false);
+
 const verb = values["dry-run"] ? "Would install" : "Installed";
 console.log(`${verb} OpenCode Goal Mode ${pkg.version} into ${target}`);
 console.log(
   `Files copied: ${summary.copied.length}; unchanged: ${summary.unchanged.length}; pruned: ${summary.pruned.length}`,
 );
+if (tuiAdded) console.log(`Registered the experimental sidebar in ${join(target, "tui.json")}`);
 console.log("Restart OpenCode for agents, commands, and plugins to load.");