opencode-usage-coach 0.13.1 → 0.13.2

package/README.md

@@ -25,32 +25,52 @@ See **[docs/architecture.md](docs/architecture.md)** for the full design.
 
 ## Quick Start
 
+### 3 steps to get running
+
+**Step 1 — Install globally (provides the `usage-coach` CLI):**
+
+```bash
+npm install -g opencode-usage-coach
+```
+
+**Step 2 — Add the server plugin to opencode:**
+
 ```jsonc
-// ~/.config/opencode/opencode.json  — server plugin
+// ~/.config/opencode/opencode.json
 { "plugin": ["opencode-usage-coach"] }
-
-// ~/.config/opencode/tui.json        — sidebar panel (point at built dist/tui.js)
-{ "$schema": "https://opencode.ai/tui.json", "plugin": ["opencode-usage-coach/tui"] }
 ```
 
-Then run setup:
+**Step 3 — Run setup (auto-configures everything else):**
 
 ```bash
-usage-coach setup          # auto-generates harness.config.json + copies agent file
-usage-coach setup --json   # machine-readable output (for scripts/CI)
+usage-coach setup
 ```
 
-This creates `~/.config/opencode-usage-coach/harness.config.json` (edit `generator`/`grader` or use `/coach-config` at runtime) and copies `agents/usage-coach-harness.md` to `~/.config/opencode/agents/`.
+This single command:
+- Creates `~/.config/opencode-usage-coach/harness.config.json` (model config)
+- Copies the harness agent file to `~/.config/opencode/agents/`
+- **Auto-configures `~/.config/opencode/tui.json`** with the correct TUI plugin path
+- Detects whether `codexbar` is installed
 
-If you use `codexbar` for quota sensing:
+Restart opencode — you're done. The sidebar panel appears (toggle with `Alt+H`).
+
+> **Without `npm install -g`:** The server plugin still works (opencode auto-installs it from npm), but `usage-coach setup` and the `usage-coach` CLI won't be available. You'd need to manually create `harness.config.json` and configure `tui.json` yourself.
+
+### Quota sensing (optional but recommended)
+
+The plugin works in **GO-only mode** out of the box (no quota sensing). To enable real-time quota monitoring, install [codexbar](https://github.com/nicepkg/codexbar):
 
 ```bash
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/nicepkg/codexbar/main/install.sh | bash
+
+# Then configure your provider API key:
 printf '%s' "$YOUR_PROVIDER_API_KEY" | codexbar config set-api-key --provider <id> --stdin
 ```
 
-Without codexbar, the plugin runs in GO-only mode (no quota sensing).
+codexbar supports any provider with a usage API (OpenAI, Anthropic, Google, z.ai, etc.). Check `codexbar providers` for the full list.
 
-For local dev without npm: `bun install && bun run build`, then point both configs at the `dist/` files.
+Without codexbar, the plugin simply doesn't sense quota — all other features (harness loop, learning, domain knowledge) work normally.
 
 ## Configuration
 
@@ -89,7 +109,13 @@ See **[docs/architecture.md](docs/architecture.md)** for details on the loop, NE
 
 ## Troubleshooting
 
-Common issues: TUI panel missing (check `tui.json` points at `dist/tui.js`, never install `solid-js` in the config dir), model selection errors (`generator` is required), and tool-abort timeouts (platform limit — split large tasks).
+**opencode crashes on startup after adding the plugin** — Make sure you're on v0.13.1 or later. Earlier versions had a bug where opencode would crash due to named exports. Run `npm install -g opencode-usage-coach@latest`.
+
+**TUI sidebar not showing** — Run `usage-coach setup` again. It auto-detects the TUI path and writes `tui.json`. If you installed via `npm install -g`, the path is `$(npm root -g)/opencode-usage-coach/dist/tui.js`. Never install `solid-js` in the opencode config directory.
+
+**`usage-coach: command not found`** — You need `npm install -g opencode-usage-coach` for the CLI. The server plugin works without it, but setup and status commands require the global install.
+
+**Model selection errors** — `generator` is required in `harness.config.json`. Run `usage-coach setup` to create it, then edit the model or use `/coach-config` at runtime.
 
 See **[docs/troubleshooting.md](docs/troubleshooting.md)** for full diagnoses and fixes.
 

package/dist/cli.js

@@ -345,6 +345,7 @@ function formatDomain(r) {
 }
 var GLOBAL_CONFIG_DIR = join(homedir(), ".config", "opencode-usage-coach");
 var OPENCODE_AGENTS_DIR = join(homedir(), ".config", "opencode", "agents");
+var OPENCODE_TUI_CONFIG = join(homedir(), ".config", "opencode", "tui.json");
 var DEFAULT_HARNESS_CONFIG = {
   generator: "opencode/deepseek-v4-flash-free",
   grader: "opencode/mimo-v2.5-free",
@@ -355,6 +356,42 @@ function resolveAgentSourceFile() {
   const scriptDir = dirname(fileURLToPath(import.meta.url));
   return join(scriptDir, "..", "agents", "usage-coach-harness.md");
 }
+function resolveTuiPath(scriptDir) {
+  const dir = scriptDir ?? dirname(fileURLToPath(import.meta.url));
+  return join(dir, "tui.js");
+}
+function configureTui(tuiPath, tuiConfigPath) {
+  if (!existsSync(tuiPath)) {
+    return { action: "not-found", path: tuiPath };
+  }
+  let config = {};
+  if (existsSync(tuiConfigPath)) {
+    try {
+      config = JSON.parse(readFileSync(tuiConfigPath, "utf8"));
+    } catch {
+      config = {};
+    }
+  }
+  const plugins = Array.isArray(config["plugin"]) ? config["plugin"] : [];
+  if (plugins.includes(tuiPath)) {
+    return { action: "exists", path: tuiConfigPath };
+  }
+  const filtered = plugins.filter(
+    (p) => !p.includes("opencode-usage-coach")
+  );
+  filtered.push(tuiPath);
+  config["plugin"] = filtered;
+  if (!config["$schema"]) {
+    config["$schema"] = "https://opencode.ai/tui.json";
+  }
+  try {
+    mkdirSync(dirname(tuiConfigPath), { recursive: true });
+    writeFileSync(tuiConfigPath, JSON.stringify(config, null, 2) + "\n");
+    return { action: "configured", path: tuiConfigPath };
+  } catch {
+    return { action: "write-error", path: tuiConfigPath };
+  }
+}
 function detectCodexbar() {
   try {
     const r = spawnSync("codexbar", ["--version"], { timeout: 5e3 });
@@ -370,6 +407,7 @@ function doSetup(opts = {}) {
   const configDir = opts.configDir ?? GLOBAL_CONFIG_DIR;
   const agentsDir = opts.agentsDir ?? OPENCODE_AGENTS_DIR;
   const agentSource = opts.agentSourceFile ?? resolveAgentSourceFile();
+  const tuiConfigPath = opts.tuiConfigPath ?? OPENCODE_TUI_CONFIG;
   const configPath = join(configDir, "harness.config.json");
   let configAction;
   if (existsSync(configPath)) {
@@ -394,10 +432,13 @@ function doSetup(opts = {}) {
     copyFileSync(agentSource, agentDestPath);
     agentAction = "copied";
   }
+  const tuiPath = resolveTuiPath(opts.scriptDir);
+  const tuiResult = configureTui(tuiPath, tuiConfigPath);
   return {
     harnessConfig: { action: configAction, path: configPath },
     codexbar,
-    agentFile: { action: agentAction, path: agentDestPath }
+    agentFile: { action: agentAction, path: agentDestPath },
+    tuiConfig: tuiResult
   };
 }
 function formatSetup(r) {
@@ -433,6 +474,20 @@ function formatSetup(r) {
     lines.push(`     Expected: ${r.agentFile.path}`);
   }
   lines.push("");
+  if (r.tuiConfig.action === "configured") {
+    lines.push(`  \u2705 TUI plugin configured`);
+    lines.push(`     ${r.tuiConfig.path}`);
+  } else if (r.tuiConfig.action === "exists") {
+    lines.push(`  \u2705 TUI plugin already configured`);
+    lines.push(`     ${r.tuiConfig.path}`);
+  } else if (r.tuiConfig.action === "not-found") {
+    lines.push(`  \u26A0\uFE0F  TUI plugin (dist/tui.js) not found`);
+    lines.push(`     Run: npm install -g opencode-usage-coach`);
+  } else {
+    lines.push(`  \u26A0\uFE0F  Could not write TUI config`);
+    lines.push(`     Manually add to ${r.tuiConfig.path}`);
+  }
+  lines.push("");
   lines.push("Setup complete. Restart opencode to apply changes.");
   return lines.join("\n");
 }
@@ -551,6 +606,7 @@ if (isDirectRun) {
   main();
 }
 export {
+  configureTui,
   doSetup,
   parseArgs,
   projectStateDir,
@@ -560,5 +616,6 @@ export {
   readRules,
   readStatus,
   resolveAgentSourceFile,
-  resolveStateDir
+  resolveStateDir,
+  resolveTuiPath
 };

package/package.json

@@ -1,29 +1,21 @@
 {
   "name": "opencode-usage-coach",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "description": "opencode closed-loop usage coach — quota SENSE -> coaching DECIDE -> loop ACT + TUI integration",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./tui": {
-      "types": "./dist/tui.d.ts",
-      "import": "./dist/tui.js"
-    },
-    "./cli": {
-      "types": "./dist/cli.d.ts",
-      "import": "./dist/cli.js"
-    }
+    ".": "./dist/index.js",
+    "./tui": "./dist/tui.js",
+    "./cli": "./dist/cli.js"
   },
   "bin": {
     "usage-coach": "./dist/cli.js"
   },
   "scripts": {
     "build": "tsup",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm test",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",