Refactor plugins to use ctx.util helpers (#54)

* Add shared plugin helper API

* Add shared plugin helpers

* Add ctx.util helpers dedup

Author: robinebers

docs/specs/2026-02-03-panel-footer-ticker-sync.md

@@ -0,0 +1,13 @@
+# Panel footer ticker sync
+
+Date: 2026-02-03
+
+## Goal
+- Ensure countdown syncs immediately when `autoUpdateNextAt` changes.
+
+## Change
+- Add optional `resetKey` to `useNowTicker` and include it in effect deps.
+- Pass `resetKey: autoUpdateNextAt` in `PanelFooter`.
+
+## Non-goals
+- No behavior changes elsewhere.

docs/specs/2026-02-03-plugin-util-dedup.md

@@ -0,0 +1,30 @@
+# Plugin util + dedup refactor
+
+Date: 2026-02-03
+
+## Goal
+- Add `ctx.util` helpers injected by host for shared JSON/HTTP/retry/time logic.
+- Refactor claude/codex/cursor plugins to use `ctx.util` helpers.
+- Align plugin tests with new ctx surface.
+- Dedup frontend plugin display state type, timer logic, settings constants.
+
+## Non-goals
+- No plugin bundling.
+- No behavior changes beyond refactor/dedup.
+
+## API additions
+- `ctx.util.tryParseJson(text)` -> value | null
+- `ctx.util.safeJsonParse(text)` -> { ok: true, value } | { ok: false }
+- `ctx.util.request(opts)` -> resp
+- `ctx.util.requestJson(opts)` -> { resp, json }
+- `ctx.util.isAuthStatus(status)` -> boolean
+- `ctx.util.retryOnceOnAuth({ request, refresh })` -> resp
+- `ctx.util.parseDateMs(value)` -> number | null
+- `ctx.util.needsRefreshByExpiry({ nowMs, expiresAtMs, bufferMs })` -> boolean
+
+## Plan
+1. Inject `ctx.util` in `src-tauri/src/plugin_engine/host_api.rs`.
+2. Refactor claude/codex/cursor plugins to use `ctx.util` helpers.
+3. Create `plugins/test-helpers.js`, update plugin tests to use it.
+4. Frontend dedup: shared `PluginDisplayState`, `useNowTicker`, settings options constants.
+5. Verify: `bun run test`, `bun run build`.

plugins/claude/plugin.js

@@ -96,18 +96,15 @@
     return out
   }
 
-  function tryParseCredentialJSON(text) {
+  function tryParseCredentialJSON(ctx, text) {
     if (!text) return null
-    const trimmed = String(text).trim()
-    if (!trimmed) return null
-    try {
-      return JSON.parse(trimmed)
-    } catch {}
+    const parsed = ctx.util.tryParseJson(text)
+    if (parsed) return parsed
 
     // Some macOS keychain items are returned by `security ... -w` as hex-encoded UTF-8 bytes.
     // Example prefix: "7b0a" ( "{\\n" ).
     // Support both plain hex and "0x..." forms.
-    let hex = trimmed
+    let hex = String(text).trim()
     if (hex.startsWith("0x") || hex.startsWith("0X")) hex = hex.slice(2)
     if (!hex || hex.length % 2 !== 0) return null
     if (!/^[0-9a-fA-F]+$/.test(hex)) return null
@@ -117,7 +114,8 @@
         bytes.push(parseInt(hex.slice(i, i + 2), 16))
       }
       const decoded = utf8DecodeBytes(bytes)
-      return JSON.parse(decoded)
+      const decodedParsed = ctx.util.tryParseJson(decoded)
+      if (decodedParsed) return decodedParsed
     } catch {}
 
     return null
@@ -128,7 +126,7 @@
     if (ctx.host.fs.exists(CRED_FILE)) {
       try {
         const text = ctx.host.fs.readText(CRED_FILE)
-        const parsed = tryParseCredentialJSON(text)
+        const parsed = tryParseCredentialJSON(ctx, text)
         if (parsed) {
           const oauth = parsed.claudeAiOauth
           if (oauth && oauth.accessToken) {
@@ -143,7 +141,7 @@
     try {
       const keychainValue = ctx.host.keychain.readGenericPassword(KEYCHAIN_SERVICE)
       if (keychainValue) {
-        const parsed = tryParseCredentialJSON(keychainValue)
+        const parsed = tryParseCredentialJSON(ctx, keychainValue)
         if (parsed) {
           const oauth = parsed.claudeAiOauth
           if (oauth && oauth.accessToken) {
@@ -174,19 +172,20 @@
     }
   }
 
-  function needsRefresh(oauth, nowMs) {
-    if (!oauth.expiresAt) return true
-    const expiresAt = Number(oauth.expiresAt)
-    if (!Number.isFinite(expiresAt)) return true
-    return nowMs + REFRESH_BUFFER_MS >= expiresAt
+  function needsRefresh(ctx, oauth, nowMs) {
+    return ctx.util.needsRefreshByExpiry({
+      nowMs,
+      expiresAtMs: oauth.expiresAt,
+      bufferMs: REFRESH_BUFFER_MS,
+    })
   }
 
   function refreshToken(ctx, creds) {
     const { oauth, source, fullData } = creds
     if (!oauth.refreshToken) return null
 
     try {
-      const resp = ctx.host.http.request({
+      const resp = ctx.util.request({
         method: "POST",
         url: REFRESH_URL,
         headers: { "Content-Type": "application/json" },
@@ -201,18 +200,17 @@
 
       if (resp.status === 400 || resp.status === 401) {
         let errorCode = null
-        try {
-          const body = JSON.parse(resp.bodyText)
-          errorCode = body.error || body.error_description
-        } catch {}
+        const body = ctx.util.tryParseJson(resp.bodyText)
+        if (body) errorCode = body.error || body.error_description
         if (errorCode === "invalid_grant") {
           throw "Session expired. Run `claude` to log in again."
         }
         throw "Token expired. Run `claude` to log in again."
       }
       if (resp.status < 200 || resp.status >= 300) return null
 
-      const body = JSON.parse(resp.bodyText)
+      const body = ctx.util.tryParseJson(resp.bodyText)
+      if (!body) return null
       const newAccessToken = body.access_token
       if (!newAccessToken) return null
 
@@ -235,7 +233,7 @@
   }
 
   function fetchUsage(ctx, accessToken) {
-    return ctx.host.http.request({
+    return ctx.util.request({
       method: "GET",
       url: USAGE_URL,
       headers: {
@@ -251,8 +249,8 @@
 
   function getResetInFromIso(ctx, isoString) {
     if (!isoString) return null
-    const ts = Date.parse(isoString)
-    if (!Number.isFinite(ts)) return null
+    const ts = ctx.util.parseDateMs(isoString)
+    if (ts === null) return null
     const diffSeconds = Math.floor((ts - Date.now()) / 1000)
     return ctx.fmt.resetIn(diffSeconds)
   }
@@ -267,42 +265,46 @@
     let accessToken = creds.oauth.accessToken
 
     // Proactively refresh if token is expired or about to expire
-    if (needsRefresh(creds.oauth, nowMs)) {
+    if (needsRefresh(ctx, creds.oauth, nowMs)) {
       const refreshed = refreshToken(ctx, creds)
       if (refreshed) accessToken = refreshed
     }
 
     let resp
+    let didRefresh = false
     try {
-      resp = fetchUsage(ctx, accessToken)
+      resp = ctx.util.retryOnceOnAuth({
+        request: (token) => {
+          try {
+            return fetchUsage(ctx, token || accessToken)
+          } catch (e) {
+            if (didRefresh) {
+              throw "Usage request failed after refresh. Try again."
+            }
+            throw "Usage request failed. Check your connection."
+          }
+        },
+        refresh: () => {
+          didRefresh = true
+          return refreshToken(ctx, creds)
+        },
+      })
     } catch (e) {
+      if (typeof e === "string") throw e
       throw "Usage request failed. Check your connection."
     }
 
-    // On 401/403, try refreshing once and retry
-    if (resp.status === 401 || resp.status === 403) {
-      const refreshed = refreshToken(ctx, creds)
-      if (!refreshed) {
-        throw "Token expired. Run `claude` to log in again."
-      }
-      try {
-        resp = fetchUsage(ctx, refreshed)
-      } catch (e) {
-        throw "Usage request failed after refresh. Try again."
-      }
-      if (resp.status === 401 || resp.status === 403) {
-        throw "Token expired. Run `claude` to log in again."
-      }
+    if (ctx.util.isAuthStatus(resp.status)) {
+      throw "Token expired. Run `claude` to log in again."
     }
 
     if (resp.status < 200 || resp.status >= 300) {
       throw "Usage request failed (HTTP " + String(resp.status) + "). Try again later."
     }
 
     let data
-    try {
-      data = JSON.parse(resp.bodyText)
-    } catch {
+    data = ctx.util.tryParseJson(resp.bodyText)
+    if (data === null) {
       throw "Usage response invalid. Try again later."
     }
 

plugins/claude/plugin.test.js

@@ -1,79 +1,11 @@
 import { beforeEach, describe, expect, it, vi } from "vitest"
+import { makeCtx } from "../test-helpers.js"
 
 const loadPlugin = async () => {
   await import("./plugin.js")
   return globalThis.__openusage_plugin
 }
 
-const makeCtx = () => {
-  const files = new Map()
-  return {
-    host: {
-      fs: {
-        exists: (path) => files.has(path),
-        readText: (path) => files.get(path),
-        writeText: vi.fn((path, text) => files.set(path, text)),
-      },
-      keychain: {
-        readGenericPassword: vi.fn(),
-        writeGenericPassword: vi.fn(),
-      },
-      http: {
-        request: vi.fn(),
-      },
-      log: {
-        error: vi.fn(),
-      },
-    },
-    line: {
-      text: (opts) => {
-        const line = { type: "text", label: opts.label, value: opts.value }
-        if (opts.color) line.color = opts.color
-        if (opts.subtitle) line.subtitle = opts.subtitle
-        return line
-      },
-      progress: (opts) => {
-        const line = { type: "progress", label: opts.label, value: opts.value, max: opts.max }
-        if (opts.unit) line.unit = opts.unit
-        if (opts.color) line.color = opts.color
-        if (opts.subtitle) line.subtitle = opts.subtitle
-        return line
-      },
-      badge: (opts) => {
-        const line = { type: "badge", label: opts.label, text: opts.text }
-        if (opts.color) line.color = opts.color
-        if (opts.subtitle) line.subtitle = opts.subtitle
-        return line
-      },
-    },
-    fmt: {
-      planLabel: (value) => {
-        const text = String(value || "").trim()
-        if (!text) return ""
-        return text.replace(/(^|\s)([a-z])/g, (match, space, letter) => space + letter.toUpperCase())
-      },
-      resetIn: (secondsUntil) => {
-        if (!Number.isFinite(secondsUntil) || secondsUntil < 0) return null
-        const totalMinutes = Math.floor(secondsUntil / 60)
-        const totalHours = Math.floor(totalMinutes / 60)
-        const days = Math.floor(totalHours / 24)
-        const hours = totalHours % 24
-        const minutes = totalMinutes % 60
-        if (days > 0) return `${days}d ${hours}h`
-        if (totalHours > 0) return `${totalHours}h ${minutes}m`
-        if (totalMinutes > 0) return `${totalMinutes}m`
-        return "<1m"
-      },
-      dollars: (cents) => Math.round((cents / 100) * 100) / 100,
-      date: (unixMs) => {
-        const d = new Date(Number(unixMs))
-        const months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
-        return months[d.getMonth()] + " " + String(d.getDate())
-      },
-    },
-  }
-}
-
 describe("claude plugin", () => {
   beforeEach(() => {
     delete globalThis.__openusage_plugin