@krishantt/opencode-go-usage 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Krishant Timilsina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @krishantt/opencode-go-usage
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+OpenCode Go usage limits — with burn-rate pacing — in the OpenCode TUI status bar.
+
+```
+GO r4% · w42% ⚠10h/2d · m21% ⚠3d/18d
+```
+
+Shows rolling / weekly / monthly quota consumption of the managed OpenCode Go
+provider, and warns when your current burn rate will exhaust a window before
+it resets.
+
+## Install
+
+Requires OpenCode v2.2+ and the OpenCode Go provider.
+
+```json title="~/.config/opencode/cli.json"
+{
+  "plugins": ["@krishantt/opencode-go-usage"]
+}
+```
+
+Restart the TUI. The indicator appears after its first fetch (up to a minute).
+
+## Reading the bar
+
+Per window: `r` rolling (5h), `w` weekly, `m` monthly, as percent consumed.
+
+| Glyph | Meaning |
+| --- | --- |
+| (none) | fine |
+| `▲` | window at ≥ 85% — nearly spent |
+| `!` | window currently rate-limited; value shows `→<time>` until reset |
+| `⚠eta/reset` | at your current pace this window hits 100% in *eta*, but only *reset* remains — plan accordingly |
+| `GO ⋯` | first fetch in flight |
+| `GO ?` | fetch failed or hung; see debug below |
+
+Pacing is linear extrapolation of your own usage (samples kept ~6 h in memory,
+rebuilds after a TUI restart) and only appears when exhaustion actually
+precedes the reset — otherwise the bar stays clean. Warns need ≥ 10 minutes
+of history per window; rolling warns only count your current 5h cycle.
+
+## Debug
+
+Run `/go-usage-debug` in the prompt (also in the Ctrl+P palette) to toggle
+fetch logging to `~/.cache/opencode/go-usage-debug.log`: raw response
+envelopes, errors with stacks, and toggle events. Off by default and resets
+to off on restart because it logs a couple of lines per poll.
+
+## Status bar placement
+
+`prompt.footer.status` and `home.footer.status` via TUI plugin slots. These
+and `context.client.experimental.usage.limits` are OpenCode v2 internals and
+may change between releases — if the bar goes missing or shows `GO ?`, check
+this repo's issues and your `~/.local/share/opencode/log/opencode.log`.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,7 @@
+import { Plugin } from "@opencode/plugin"
+
+// Server part is empty; all behavior lives in ./tui.tsx
+export default Plugin.define({
+  id: "go-usage",
+  setup() {},
+})

package/package.json

@@ -1,6 +1,33 @@
 {
+  "$schema": "https://json.schemastore.org/package.json",
   "name": "@krishantt/opencode-go-usage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "description": "OpenCode TUI plugin: OpenCode Go usage limits plus burn-rate pacing warnings in the status bar",
+  "keywords": [
+    "opencode",
+    "opencode-go",
+    "opencode-plugin",
+    "opencode-tui",
+    "usage",
+    "usage-limits",
+    "quota",
+    "pacing",
+    "rate-limits"
+  ],
+  "license": "MIT",
+  "author": "Krishant Timilsina",
+  "repository": "github:krishantt/opencode-go-usage",
+  "exports": {
+    ".": "./index.ts",
+    "./tui": "./tui.tsx"
+  },
+  "dependencies": {
+    "@opencode/plugin": "latest"
+  },
+  "peerDependencies": {
+    "@opentui/core": ">=0.6.6",
+    "@opentui/solid": ">=0.6.6",
+    "solid-js": ">=1.9.0"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "//": "Bun reads this file when transpiling tui.tsx. OpenCode's TUI solid-transform skips node_modules paths, so the npm-installed copy relies on Bun's default JSX unless this sets the opentui runtime.",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@opentui/solid"
+  }
+}

package/tui.tsx

@@ -0,0 +1,128 @@
+import { Plugin } from "@opencode/plugin/tui"
+import { appendFileSync } from "node:fs"
+
+// debug sink, written when the toggle flag is on
+const DEBUG_LOG = `${process.env.HOME}/.cache/opencode/go-usage-debug.log`
+
+type Window = { percent?: number, resetsAt?: number, limited?: boolean }
+
+// Burn-rate history: one sample per poll with all three windows; 6h cap.
+type Sample = { t: number, p: number[] }
+
+// Humanize milliseconds to a compact duration like 4h or 2d.
+function human(ms: number): string {
+  if (ms < 0) return "now"
+  const h = ms / 3.6e6
+  if (h >= 48) return `${Math.round(h / 24)}d`
+  if (h >= 1) return `${Math.round(h)}h`
+  return `${Math.max(1, Math.round(ms / 6e4))}m`
+}
+
+// "⚠eta/reset" when the window's own burn slope hits 100% before its reset,
+// "" otherwise. Resets appear as drops, so analysis starts after the last one.
+function pace(samples: { t: number, p: number }[], resetsAt: number | undefined, now: number): string {
+  if (samples.length < 2) return ""
+  let start = 0
+  for (let i = 1; i < samples.length; i++)
+    if (samples[i]!.p < samples[i - 1]!.p) start = i
+  const run = samples.slice(start)
+  const first = run[0]!
+  const last = run[run.length - 1]!
+  const mins = (last.t - first.t) / 6e4
+  if (mins < 10) return ""
+  const perMin = (last.p - first.p) / mins
+  if (perMin <= 0) return ""
+  const etaMin = (100 - last.p) / perMin
+  const remainMin = ((resetsAt ?? 0) - now) / 6e4
+  if (etaMin <= 0 || etaMin >= remainMin) return ""
+  return ` ⚠${human(etaMin * 6e4)}/${human(remainMin * 6e4)}`
+}
+
+export default Plugin.define({
+  id: "go-usage",
+  setup(context) {
+    // windows: go rolling/weekly/monthly; ok=false -> "GO ?"
+    const [state, update] = context.storage.memory("go-usage", {
+      initial: { windows: [] as Window[], ok: true, samples: [] as Sample[], dbg: false },
+    })
+    const dbg = (msg: string) => {
+      if (!state.dbg) return
+      try { appendFileSync(DEBUG_LOG, `${new Date().toISOString()} ${msg}\n`) } catch {}
+    }
+
+    // feature-detect: client.experimental.usage.limits, older client.usage.limits
+    const anyClient = context.client as any
+    const call = anyClient?.experimental?.usage?.limits ?? anyClient?.usage?.limits
+
+    const refresh = async () => {
+      if (!call) { update((d) => { d.ok = false }); dbg("client method missing"); return }
+      try {
+        const res = await call()
+        dbg(`raw: ${JSON.stringify(res)?.slice(0, 300) ?? String(res)}`)
+        const data = res?.data ?? res
+        const go = data?.go
+        if (!go) throw new Error("no go data")
+        const pick = (w: unknown) => (w ?? {}) as Window
+        update((d) => {
+          d.ok = true
+          d.windows = [pick(go.rolling), pick(go.weekly), pick(go.monthly)]
+          // memory store predating samples (hot reload) and fetch errors both land here
+          d.samples = (d.samples ?? []).concat({ t: Date.now(), p: d.windows.map((w: Window) => Math.round(w.percent ?? 0)) })
+          const cutoff = Date.now() - 6 * 3.6e6
+          d.samples = d.samples.filter((s: Sample) => s.t > cutoff).slice(-400)
+        })
+      }
+      catch (e) {
+        dbg(`error: ${e instanceof Error ? e.stack : String(e)}`)
+        update((d) => {
+          d.ok = false
+        })
+      }
+    }
+    refresh()
+    // a fetch that hangs must not blank the status bar forever
+    const failTimer = setTimeout(() => {
+      if (state.windows.length === 0) update((d) => { d.ok = false })
+    }, 10_000)
+    const timer = setInterval(refresh, 60_000)
+
+    const render = () => {
+      if (!state.ok)
+        return <text fg={context.theme.text.muted}>{"GO ?"}</text>
+      if (state.windows.length === 0)
+        return <text fg={context.theme.text.muted}>{"GO ⋯"}</text>
+      const parts = state.windows.map((w: Window, i: number) => {
+        const pct = Math.round(w.percent ?? 0)
+        // glyph prefix stands in for color: ! = rate-limited, ▲ = nearly spent
+        const mark = w.limited ? "!" : pct >= 85 ? "▲" : ""
+        const reset = w.limited ? `→${human((w.resetsAt ?? 0) - Date.now())}` : ""
+        const warn = pace(state.samples.map((s: Sample) => ({ t: s.t, p: s.p[i] ?? 0 })), w.resetsAt, Date.now())
+        return `${mark}${["r", "w", "m"][i]}${pct}%${reset}${warn}`
+      })
+      return <text fg={context.theme.text.muted}>{`GO ${parts.join(" · ")}`}</text>
+    }
+
+    context.ui.slot({ append: "prompt.footer.status", render })
+    context.ui.slot({ append: "home.footer.status", render })
+    context.keymap.layer(() => ({
+      mode: "global",
+      commands: [
+        {
+          id: "go-usage.debug",
+          title: "go-usage: toggle debug logging",
+          group: "go-usage",
+          palette: true,
+          slash: { name: "go-usage-debug" },
+          run() {
+            update((d) => { d.dbg = !d.dbg })
+            const on = state.dbg
+            dbg(`debug toggled ${on ? "on" : "off"}`)
+            context.ui.toast.show({ title: "go-usage", message: `debug ${on ? "on → " + DEBUG_LOG : "off"}`, duration: 4000 })
+          },
+        },
+      ],
+      bindings: ["go-usage.debug"],
+    }))
+    return () => { clearInterval(timer); clearTimeout(failTimer) }
+  },
+})