opencode-goal-mode 0.3.6 → 0.3.7

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## v0.3.7
+
+- **FIX: the sidebar now actually loads.** OpenCode loads a TUI plugin via the
+  package's `exports["./tui"]` subpath (verified against the OpenCode binary), and
+  ours had no `exports`, so it silently never loaded. The package now maps
+  `"./tui"` (and `main`) to `plugins/goal-sidebar.tsx`, and the entry is shipped as
+  `.tsx` so OpenCode transpiles it. Confirmed working in a real OpenCode 1.17.6 TUI.
+- **Sidebar layout, as requested:** three stacked lines — `GOAL  <title>`, then the
+  gate count (`n/m gates`), then the status (`in progress` / `… · changes pending`
+  / `completed · k review cycles`). The leading orb (◆) is removed.
+- **AI-generated goal title:** `goal_contract` takes a short `title` the Goal agent
+  writes (the objective, like a session title); the sidebar shows it, falling back
+  to the raw goal text until titled.
+- **One-command install:** `npx opencode-goal-mode --global` (new `opencode-goal-mode`
+  bin alias). The installer registers the sidebar in `tui.json` (merge-safe) and
+  `--uninstall` removes that entry too. Install instructions moved to the top of the
+  README.
+- Colours configurable: `sidebarColor` (running), `sidebarDoneColor` (done),
+  `sidebarMutedColor` (no goal).
+
 ## v0.3.6
 
 - **FIX: the sidebar never loaded.** TUI plugins are loaded from

package/README.md

@@ -8,21 +8,49 @@
 [![node](https://img.shields.io/node/v/opencode-goal-mode?color=2da44e)](package.json)
 
 Strict Goal Mode for OpenCode: a primary `goal` agent, a matrix of specialized
-review subagents, slash commands, and a `goal-guard` plugin that enforces review
-discipline, blocks destructive shell commands, and preserves goal state across
-compaction **and** restarts.
+review subagents, slash commands, a `goal-guard` plugin that enforces review
+discipline and blocks destructive shell commands, and a live goal banner in the
+TUI sidebar.
+
+## Install
+
+**One command** (needs [Node](https://nodejs.org) 20.11+ and [OpenCode](https://opencode.ai)):
+
+```bash
+npx opencode-goal-mode --global
+```
+
+Then **restart OpenCode**. That's the whole install — it copies the Goal agent,
+review subagents, slash commands, and the guard plugin into `~/.config/opencode`,
+and registers the sidebar in `~/.config/opencode/tui.json`. In the agent picker
+you'll see only the **`goal`** agent (the reviewers are subagents it drives).
+
+<details>
+<summary>Other ways to install</summary>
 
 ```bash
-npm install -g opencode-goal-mode && opencode-goal-mode-install --global
+# Global npm install, then run the installer
+npm install -g opencode-goal-mode
+opencode-goal-mode --global          # alias of opencode-goal-mode-install
+
+# Into a single project (writes ./.opencode + ./tui.json)
+npx opencode-goal-mode
+
+# From source
+git clone https://github.com/devinoldenburg/opencode-goal-mode
+cd opencode-goal-mode && npm ci && npm run install:global
 ```
 
+`--dry-run` previews changes; `--uninstall` removes only what it installed (and its
+tui.json entry), leaving your edits untouched. See [Installer options](#installer-options).
+</details>
+
 ![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>
+<sub>↑ The sidebar goal banner: yellow while a goal runs, red when done, grey "No
+goal available" otherwise — 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](#quick-start) · [Why it's different](#why-its-different) · [Benchmarks](#benchmarks-honest-edition) · [TUI integration](#tui-integration) · [Configuration](#configuration) · [Releasing](#releasing) · [Architecture](ARCHITECTURE.md)**
 
 ## Quick start
 
@@ -205,40 +233,6 @@ enforcement and writes its state to disk, and an experimental TUI plugin
   (`toastOnReview`), and blocked destructive commands / premature completions
   toast as before (`toastOnBlock`).
 
-## Install
-
-### From npm (recommended)
-
-```bash
-npm install -g opencode-goal-mode
-opencode-goal-mode-install --global    # installs into ~/.config/opencode
-```
-
-Then restart OpenCode (it loads agents, commands, and plugins at startup). In the
-agent picker you will see **only the `goal` agent** — the specialist reviewers are
-subagents the Goal agent drives for you; they are never selectable by the user.
-
-Install into a single project instead of globally:
-
-```bash
-npm install -D opencode-goal-mode
-npx opencode-goal-mode-install         # writes to ./.opencode
-```
-
-Upgrade later by re-running the same install command after `npm install -g
-opencode-goal-mode@latest`; the installer replaces only the files it owns and
-leaves your local edits alone (see [Installer options](#installer-options)).
-
-### From source
-
-```bash
-git clone https://github.com/devinoldenburg/opencode-goal-mode
-cd opencode-goal-mode
-npm ci
-npm run validate
-npm run install:global                 # or: npm run install:local
-```
-
 ## Installer options
 
 ```bash

package/agents/goal.md

@@ -85,7 +85,7 @@ Required internal artifacts:
 
 Guard tools (provided by the goal-guard plugin):
 
-- Call `goal_contract` once the Goal Contract is settled. This activates strict enforcement and tells the guard which specialist review gates your goal requires (security, data, api, perf, etc., inferred from the contract text).
+- Call `goal_contract` once the Goal Contract is settled. Always include a concise `title` (max ~8 words, no trailing punctuation) that captures what the user ultimately wants — phrased like a session title but about the objective (e.g. "Rate-limit the login endpoint", "Migrate auth to JWT"). This title is shown live in the TUI sidebar, so make it specific and readable. Recording the contract activates strict enforcement and tells the guard which specialist review gates your goal requires (security, data, api, perf, etc., inferred from the contract text).
 - Call `goal_evidence` after each meaningful verification run to record the command and result in the Verification Ledger.
 - Call `goal_status` whenever you are unsure what the guard currently requires; it returns the authoritative list of passing, missing, and stale gates and whether completion is allowed. Trust it over your own recollection.
 - The guard injects a live state block into your context each turn and will rewrite a premature `Goal Completed` into `Goal Not Completed` with the missing gates. Use `goal_status` to avoid that rather than guessing.

package/commands/goal.md

@@ -11,11 +11,12 @@ $ARGUMENTS
 
 Run this sequence:
 
-1. **Seed the contract first.** Call the `goal_contract` tool with the original
-   request, explicit/inferred requirements, non-goals, and concrete acceptance
-   criteria. This activates enforcement, fixes the required specialist review
-   gates, and lights up the goal banner in the sidebar. Ask only essential
-   clarifying questions before recording it.
+1. **Seed the contract first.** Call the `goal_contract` tool with a concise
+   `title` (≤8 words, what the user ultimately wants — like a session title for
+   the objective), the original request, explicit/inferred requirements,
+   non-goals, and concrete acceptance criteria. This activates enforcement, fixes
+   the required specialist review gates, and shows the `title` live in the sidebar
+   goal banner. Ask only essential clarifying questions before recording it.
 2. Delegate discovery and research to subagents; implement in the main agent.
 3. Verify, and record each verification with the `goal_evidence` tool so it maps
    to your acceptance criteria.

package/package.json

@@ -1,14 +1,20 @@
 {
   "name": "opencode-goal-mode",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Strict Goal Mode agents, commands, and guard plugin for OpenCode.",
   "type": "module",
-  "main": "plugins/goal-sidebar.js",
+  "main": "plugins/goal-sidebar.tsx",
+  "exports": {
+    ".": "./plugins/goal-sidebar.tsx",
+    "./tui": "./plugins/goal-sidebar.tsx",
+    "./package.json": "./package.json"
+  },
   "engines": {
     "node": ">=20.11"
   },
   "packageManager": "npm@10",
   "bin": {
+    "opencode-goal-mode": "scripts/install.mjs",
     "opencode-goal-mode-install": "scripts/install.mjs"
   },
   "files": [

package/plugins/goal-guard/summary.js

@@ -6,12 +6,18 @@
 import { requiredGates, missingGates, gatePassedFresh } from "./gates.js";
 
 /**
- * A short, single-line human label for the current goal — preferring the
- * recorded Goal Contract's original request, falling back to the captured goal
- * text. Collapses whitespace and truncates to `max` chars for compact display
- * (status reports, the TUI sidebar banner).
+ * A short, single-line label for the current goal.
+ *
+ * Prefers `contract.title` — a concise, AI-generated summary of the objective
+ * (what the user wants), written by the Goal agent when it records the contract
+ * via `goal_contract` (think "session title", but the goal/objective). Falls back
+ * to the contract's original request, then the captured goal text, so something
+ * sensible still shows before the agent has titled the goal. Collapses whitespace
+ * and truncates to `max` chars for the compact sidebar.
  */
 export function shortGoalLabel(state, max = 80) {
+  const title = String(state?.contract?.title || "").replace(/\s+/g, " ").trim();
+  if (title) return title.length <= max ? title : `${title.slice(0, max - 1).trimEnd()}…`;
   const raw = String(state?.contract?.original || state?.goalText || "").replace(/\s+/g, " ").trim();
   if (!raw) return "";
   // Prefer the first sentence/clause if it is reasonably short.
@@ -22,17 +28,17 @@ export function shortGoalLabel(state, max = 80) {
 }
 
 /** 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: "" });
+export const NO_GOAL = Object.freeze({ state: "none", goal: "", gates: "", status: "" });
 
 /**
  * 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.
+ * three-way `state`, plus three lines that stack vertically in the sidebar:
+ *   - `goal`   → line 1: the short AI goal title.
+ *   - `gates`  → line 2: the gate count, e.g. "0/7 gates".
+ *   - `status` → line 3: the lifecycle status, e.g. "in progress · changes pending"
+ *                or "completed · 2 review cycles".
+ * State drives colour: "running" = yellow, "done" = red, "none" = grey
+ * ("No goal available").
  */
 export function sidebarView(state, config) {
   if (!state || !state.active) return NO_GOAL;
@@ -42,24 +48,24 @@ export function sidebarView(state, config) {
   const missing = missingGates(state, config);
   const passing = required.length - missing.length;
   const cycles = Number(state.reviewCycles) || 0;
+  const gates = `${passing}/${required.length} gates`;
   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"}`,
+      gates,
+      status: `completed · ${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(" · ")}`,
+    gates,
+    status: `in progress${state.dirty ? " · changes pending" : ""}`,
     passing,
     required: required.length,
     reviewCycles: cycles,

package/plugins/goal-guard/tools.js

@@ -92,6 +92,13 @@ export function createGoalTools({ store, config, persist }) {
         "inferred requirements, non-goals, and acceptance criteria). Establishing a contract " +
         "activates strict goal enforcement and drives which specialist review gates are required.",
       args: {
+        title: s
+          .string()
+          .describe(
+            "A short (max ~8 words) human-friendly title summarizing the GOAL/objective — what the user " +
+              "ultimately wants, phrased like a session title but about the outcome. Shown in the TUI sidebar. " +
+              "e.g. 'Rate-limit the login endpoint', 'Migrate auth to JWT'. No trailing punctuation.",
+          ),
         original: s.string().describe("The original user request, verbatim or faithfully summarized."),
         requirements: s.array(s.string()).optional().describe("Explicit requirements stated by the user."),
         inferred: s.array(s.string()).optional().describe("Reasonable inferred requirements."),
@@ -104,6 +111,7 @@ export function createGoalTools({ store, config, persist }) {
         const state = store.stateFor(ctx.sessionID);
         state.active = true;
         state.contract = {
+          title: String(args.title || "").replace(/\s+/g, " ").trim(),
           original: String(args.original || ""),
           requirements: args.requirements || [],
           inferred: args.inferred || [],

package/plugins/{goal-sidebar.js → goal-sidebar.tsx}

@@ -2,36 +2,32 @@
 /**
  * Goal Mode — TUI sidebar goal banner.
  *
- * 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"
+ * Renders, in the sidebar's content area, the current goal as three stacked lines:
+ *   1. `GOAL  <short AI title>`   (the objective, generated by the Goal agent)
+ *   2. `<n>/<m> gates`            (review-gate progress)
+ *   3. `<status>`                 (in progress / changes pending / completed …)
+ * Colour tracks lifecycle: yellow while running, red when done, grey
+ * "No goal available" when a task has no goal set.
  *
- * 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.
+ * How OpenCode loads this: TUI plugins are listed in `~/.config/opencode/tui.json`
+ * (NOT the plugins/ dir) and resolved via the package's `exports["./tui"]`. The
+ * installer writes tui.json (`plugin: ["opencode-goal-mode"]`); package.json maps
+ * `./tui` → this file; OpenCode supplies the `@opentui/solid` + `solid-js` runtime
+ * (declared as peer deps). The pure projection (`summary.sidebarView`) is shared
+ * with the server plugin and unit-tested via goal-guard/sidebar-data.js.
  *
- * 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).
+ * Runtime notes: single `export default { id, tui }`; node built-ins are require()d
+ * lazily (the Bun TUI runtime rejects top-level node: imports). Never imported by
+ * the Node test suite.
  */
 
 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 — running
-const DEFAULT_DONE = "#FF5555"; // red — completed
-const DEFAULT_MUTED = "#808080"; // grey — no goal
+const DEFAULT_COLOR = "#FFD700"; // running — yellow
+const DEFAULT_DONE = "#FF5555"; // done — red
+const DEFAULT_MUTED = "#808080"; // no goal — grey
 const POLL_MS = 1500;
 
 function resolveOptions(options, env) {
@@ -119,20 +115,16 @@ const tui = async (api, options) => {
           const timer = setInterval(() => setModel(read()), POLL_MS);
           onCleanup(() => clearInterval(timer));
           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.
+          // Three stacked lines: GOAL+title, gates, status — or grey "No goal available".
           return (
             <box flexDirection="column" paddingTop={1}>
-              <Show
-                when={model().state !== "none"}
-                fallback={<text fg={muted}>No goal available</text>}
-              >
+              <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={fg()}>{model().detail}</text>
+                <text fg={fg()}>{model().gates}</text>
+                <text fg={fg()}>{model().status}</text>
               </Show>
             </box>
           );