opencode-context-indicator 1.0.0

package/lib/dedup.js

@@ -0,0 +1,120 @@
+// lib/dedup.js
+//
+// Shared helpers for the local OpenCode plugins in ../ (V2 + V1 dual format).
+//
+// WHY THIS FILE LIVES IN A SUBDIRECTORY WITHOUT AN INDEX FILE
+//   The V2 plugin loader auto-discovers entries under the plugins/ directory.
+//   A *directory* entry is treated as a plugin only when it contains an index
+//   file (docs: ".opencode/plugins/example/index.ts"); a directory without one
+//   is ignored entirely (verified empirically against opencode 2.0.16:
+//   plugins/lib/index.js showed up as a plugin, plugins/libprobe2/dedup.js did
+//   not). Keeping the shared helpers in ./lib/dedup.js therefore lets other
+//   plugin files `import` them with a plain relative specifier — the documented
+//   multi-file plugin pattern — WITHOUT registering a phantom no-op plugin.
+//   The default export below is still a valid no-op plugin definition as
+//   defense-in-depth, so the file stays inert even if a future loader starts
+//   discovering non-index modules.
+//
+// EXPORTS
+//   claimOnce(key, dedupDir)  atomic cross-instance / cross-process claim
+//   pruneDedup(dedupDir)      delete claim markers older than DEDUP_TTL_MS
+//   pruneMap(map, maxSize)    LRU-trim an in-process Map
+//   DEDUP_TTL_MS              marker lifetime (24h)
+//
+// The claim mechanism is the exact one proven in token-usage-logger.js:
+// OpenCode loads one plugin instance per loaded location and mirrors the public
+// event stream to every instance, so without an atomic claim each logical event
+// would be recorded once per location. An exclusive-create file marker ("wx")
+// makes exactly one instance win. Fail-open: if the marker cannot be created
+// for an unexpected reason the event is still recorded (never lose data over
+// bookkeeping).
+
+import {
+  closeSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  statSync,
+  unlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+
+export const DEDUP_TTL_MS = 24 * 60 * 60 * 1000; // prune claim markers after a day
+// Time-throttled pruning. A claim directory can hold tens of thousands of
+// markers (mostly legacy per-delta markers), and pruneDedup() does a
+// synchronous readdirSync+statSync over the whole directory — running that in
+// the event-loop hot path stalls the event stream. Pruning therefore runs at
+// most once per PRUNE_MIN_INTERVAL_MS. The timestamp is seeded at module load
+// so the first claim after startup does NOT trigger a scan (keeping startup /
+// first events off the scan path); the first prune happens on the first claim
+// at least PRUNE_MIN_INTERVAL_MS after load.
+const PRUNE_MIN_INTERVAL_MS = 10 * 60 * 1000; // at most one prune / 10 minutes
+let lastPruneAt = Date.now();
+
+function logErr(msg, err) {
+  try {
+    console.error(`[plugin-lib] ${msg}:`, err);
+  } catch {
+    /* ignore */
+  }
+}
+
+// Trim an in-process Map to at most `maxSize` entries (insertion order).
+export function pruneMap(map, maxSize) {
+  if (!map || map.size <= maxSize) return;
+  const excess = map.size - maxSize;
+  let removed = 0;
+  for (const key of map.keys()) {
+    if (removed >= excess) break;
+    map.delete(key);
+    removed++;
+  }
+}
+
+// Atomic, cross-instance, cross-process exactly-once claim.
+// Returns true when this caller won the claim (or on fail-open), false when the
+// marker already existed (another instance already claimed it).
+export function claimOnce(key, dedupDir) {
+  try {
+    mkdirSync(dedupDir, { recursive: true });
+    const safe = String(key).replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 200);
+    const fd = openSync(join(dedupDir, `${safe}.seen`), "wx");
+    closeSync(fd);
+    const now = Date.now();
+    if (now - lastPruneAt >= PRUNE_MIN_INTERVAL_MS) {
+      lastPruneAt = now;
+      pruneDedup(dedupDir);
+    }
+    return true;
+  } catch (err) {
+    if (err && err.code === "EEXIST") return false;
+    logErr("claimOnce failed (fail-open)", err);
+    return true; // fail open
+  }
+}
+
+// Delete claim markers older than DEDUP_TTL_MS. Never throws.
+export function pruneDedup(dedupDir) {
+  try {
+    const now = Date.now();
+    for (const f of readdirSync(dedupDir)) {
+      try {
+        const p = join(dedupDir, f);
+        if (now - statSync(p).mtimeMs > DEDUP_TTL_MS) unlinkSync(p);
+      } catch {
+        /* ignore single file */
+      }
+    }
+  } catch {
+    /* ignore (dir missing / transient) */
+  }
+}
+
+// Valid no-op plugin definition (see "WHY THIS FILE LIVES ..." above).
+export default {
+  id: "plugin-lib",
+  async setup() {},
+  async server() {
+    return {};
+  },
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "opencode-context-indicator",
+  "version": "1.0.0",
+  "description": "Real-time OpenCode context-window usage indicator: per-category token breakdown written to a log file, plus an optional TUI sidebar. Dual V1 + V2 plugin entry.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./index.js",
+    "./tui": "./tui.tsx"
+  },
+  "files": [
+    "index.js",
+    "lib/",
+    "tui.tsx",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "context",
+    "tokens",
+    "usage",
+    "tui",
+    "sidebar"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "VladSmr",
+  "repository": { "type": "git", "url": "git+https://github.com/VladSmr/opencode-context-indicator.git" },
+  "homepage": "https://github.com/VladSmr/opencode-context-indicator#readme",
+  "bugs": { "url": "https://github.com/VladSmr/opencode-context-indicator/issues" },
+  "peerDependencies": {
+    "@opencode/plugin": ">=2.0.16",
+    "@opentui/core": ">=0.5.12",
+    "@opentui/solid": ">=0.5.12",
+    "solid-js": ">=1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@opencode/plugin": {
+      "optional": true
+    },
+    "@opentui/core": {
+      "optional": true
+    },
+    "@opentui/solid": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    }
+  }
+}

package/tui.tsx

@@ -0,0 +1,180 @@
+/**
+ * tui.tsx — optional OpenCode TUI sidebar for `opencode-context-indicator`.
+ *
+ * Exposed as the `./tui` package entry ("beside the main plugin for automatic
+ * loading"). OpenCode loads it only in the terminal TUI; it is NOT loaded in
+ * the Desktop app (Desktop exposes no TUI slot API). It renders the
+ * per-category context breakdown produced by the server plugin (index.js) into
+ * the session sidebar via `append: "sidebar.content"`.
+ *
+ * Data bridge: the server plugin rewrites
+ *   %TEMP%/opencode-context-indicator-state.json
+ * (see writeStateFile() in index.js) on every breakdown update. This module
+ * ONLY reads that file and re-polls it once per second; a missing or corrupt
+ * file renders "no data yet". The main plugin never imports this file, so the
+ * absence of the OpenTUI peers cannot break the server/V1 path.
+ *
+ * Peer requirements (declared optional in package.json): @opentui/core,
+ * @opentui/solid, solid-js.
+ */
+import {Plugin, usePlugin} from "@opencode/plugin/tui"
+import {createSignal, Show} from "solid-js"
+import {readFileSync} from "node:fs"
+import {tmpdir} from "node:os"
+import {join} from "node:path"
+
+const STATE_FILE = join(tmpdir(), "opencode-context-indicator-state.json")
+const POLL_MS = 1000
+const LABEL_WIDTH = 12
+
+type Categories = {
+  user?: number
+  assistant?: number
+  reasoning?: number
+  toolArgs?: number
+  system?: number | null
+  toolSchemas?: number | null
+  other?: number
+}
+
+type StateEntry = {
+  sessionID?: string
+  model?: string
+  providerID?: string
+  ctx?: number
+  input?: number
+  usable?: number | null
+  limit?: number | null
+  reasoning?: number
+  categories?: Categories
+  updatedAt?: string
+}
+
+function fmt(n: number): string {
+  if (!Number.isFinite(n)) return "0"
+  return n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(Math.round(n))
+}
+
+function num(v: unknown): number {
+  return typeof v === "number" && Number.isFinite(v) ? v : 0
+}
+
+// Theme tokens are OpenTUI RGBA values (see ResolvedTheme.text.base/.muted);
+// pass them straight to the renderer. Fall back to a named color when a token
+// is absent so an unexpected theme shape can never blank the sidebar.
+type Fg = string | object
+function token(v: unknown, fallback: string): Fg {
+  return v && typeof v === "object" ? (v as Fg) : fallback
+}
+
+// Read the snapshot entry for one session. Never throws: a missing, empty or
+// corrupt state file simply yields null ("no data yet").
+function readEntry(sessionID: string | undefined): StateEntry | null {
+  if (!sessionID) return null
+  try {
+    const raw = readFileSync(STATE_FILE, "utf8")
+    const all = JSON.parse(raw) as Record<string, StateEntry>
+    if (!all || typeof all !== "object" || Array.isArray(all)) return null
+    const entry = all[sessionID]
+    return entry && typeof entry === "object" ? entry : null
+  } catch {
+    return null
+  }
+}
+
+function updatedAt(iso: string | undefined): string {
+  if (!iso) return "?"
+  try {
+    return new Date(iso).toLocaleTimeString()
+  } catch {
+    return "?"
+  }
+}
+
+function Sidebar(props: { entry: () => StateEntry | null }) {
+  const context = usePlugin()
+  const base = () => token(context?.theme?.text?.base, "white")
+  const muted = () => token(context?.theme?.text?.muted, base())
+
+  const e = () => props.entry()
+
+  const denom = (): number | null => {
+    const x = e()
+    const d = x?.usable ?? x?.limit
+    return typeof d === "number" && d > 0 ? d : null
+  }
+  const pct = (v: number): string => {
+    const d = denom()
+    return d ? `${Math.round((v / d) * 100)}%` : ""
+  }
+  const line = (label: string, v: unknown): string => {
+    const n = num(v)
+    const l = (label + " ".repeat(LABEL_WIDTH)).slice(0, LABEL_WIDTH)
+    const p = pct(n)
+    return `${l}${fmt(n).padStart(7)}${p ? `  ${p.padStart(4)}` : ""}`
+  }
+  const header = (): string => {
+    const x = e()
+    if (!x) return ""
+    const d = denom()
+    return `${x.model ?? "?"} · ${fmt(num(x.ctx))}${
+      d ? ` / ${fmt(d)}` : ""
+    }${d ? ` (${pct(num(x.ctx))})` : ""}`
+  }
+
+  return (
+    <box flexDirection="column">
+      <text fg={base()}>{"Context"}</text>
+      <Show when={e()} fallback={<text fg={muted()}>{"  no data yet"}</text>}>
+        <text fg={base()}>{header()}</text>
+        <text fg={muted()}>{line("user", e()?.categories?.user)}</text>
+        <text fg={muted()}>{line("assistant", e()?.categories?.assistant)}</text>
+        <text fg={muted()}>{line("reasoning", e()?.categories?.reasoning)}</text>
+        <text fg={muted()}>{line("tool args", e()?.categories?.toolArgs)}</text>
+        <text fg={muted()}>
+          {e()?.categories?.system == null
+            ? `${"system".padEnd(LABEL_WIDTH)}     n/a`
+            : line("system", e()?.categories?.system)}
+        </text>
+        <text fg={muted()}>
+          {e()?.categories?.toolSchemas == null
+            ? `${"tool schemas".padEnd(LABEL_WIDTH)}     n/a`
+            : line("tool schemas", e()?.categories?.toolSchemas)}
+        </text>
+        <text fg={muted()}>{line("other", e()?.categories?.other)}</text>
+        <text fg={muted()}>{`updated ${updatedAt(e()?.updatedAt)}`}</text>
+      </Show>
+    </box>
+  )
+}
+
+export default Plugin.define({
+  id: "context-indicator.tui",
+  setup(context) {
+    // Re-read the bridge file once per second and re-render reactively.
+    const [tick, setTick] = createSignal(0)
+    let currentSession: string | undefined
+    const entry = (): StateEntry | null => {
+      tick() // track the ticker so reads re-run every poll
+      return readEntry(currentSession)
+    }
+    const timer = setInterval(() => setTick((n) => n + 1), POLL_MS)
+
+    const unregister = context.ui.slot({
+      append: "sidebar.content",
+      render: ({ sessionID }) => {
+        currentSession = sessionID
+        return <Sidebar entry={entry} />
+      },
+    })
+
+    return () => {
+      clearInterval(timer)
+      try {
+        unregister?.()
+      } catch {
+        /* ignore */
+      }
+    }
+  },
+})