opencode-extended-sidebar 0.2.90

package/src/pware.oc.core/pware.oc.core.debug.ts

@@ -0,0 +1,280 @@
+/**
+ * Optional file-based debug + profile loggers, plus a tiny on-screen event
+ * ring for the sidebar's read-only debug console.
+ *
+ * Debug:   OES_DEBUG_OPENCODE=1          → writes to <plugin>/logs/
+ * Profile: OES_DEBUG_PROFILE=1           → writes to <plugin>/logs/
+ * Either  OES_DEBUG_*=/some/dir          → writes to that directory
+ *
+ * Each session appends a single oes-debug-<date>.log / oes-profile-<date>.log
+ * file. Lines are newline-delimited JSON:
+ *   debug   → { ts, tag, msg, data? }
+ *   profile → { ts, tag, ms, data? }
+ * All writes are silent on error — the plugin never crashes because of logging.
+ *
+ * The screen ring (`pushScreenLine`) is a module-level 200-line buffer of short
+ * labels (e.g. `db open`) that the sidebar console subscribes to; it is only
+ * fed while a logger is active, so production pays nothing.
+ */
+import fs from "node:fs"
+import path from "node:path"
+import { pluginRoot } from "./pware.oc.core.paths.js"
+
+const DEBUG_ENV_KEY = "OES_DEBUG_OPENCODE"
+const PROFILE_ENV_KEY = "OES_DEBUG_PROFILE"
+
+function pluginLogsDir(): string {
+  return path.join(pluginRoot(), "logs")
+}
+
+function resolveLogDir(
+  envKey: string,
+  env: Record<string, string | undefined>,
+  defaultDir?: string,
+): string | null {
+  const val = env[envKey]
+  if (!val) return null
+  const trimmed = val.trim()
+  if (!trimmed) return null
+  const FALSY = new Set(["0", "false", "no", "off"])
+  if (FALSY.has(trimmed.toLowerCase())) return null
+  const TRUTHY = new Set(["1", "true", "yes", "on"])
+  if (TRUTHY.has(trimmed.toLowerCase())) return defaultDir ?? pluginLogsDir()
+  return trimmed
+}
+
+/** Returns the debug log directory, or null when debug is off. Exported for tests. */
+export function debugLogDir(
+  env: Record<string, string | undefined> = process.env,
+  defaultDir?: string,
+): string | null {
+  return resolveLogDir(DEBUG_ENV_KEY, env, defaultDir)
+}
+
+/** Returns the profile log directory, or null when profiling is off. Exported for tests. */
+export function profileLogDir(
+  env: Record<string, string | undefined> = process.env,
+  defaultDir?: string,
+): string | null {
+  return resolveLogDir(PROFILE_ENV_KEY, env, defaultDir)
+}
+
+/** True when the debug logger is active — env on AND its log dir resolved/writable. */
+export function debugActive(): boolean {
+  return resolvedDir() !== null
+}
+
+export function debugActiveDir(): string | null {
+  return resolvedDir()
+}
+
+/** True when the profile logger is active — env on AND its log dir resolved/writable. */
+export function profileActive(): boolean {
+  return profileResolvedDir() !== null
+}
+
+export function profileActiveDir(): string | null {
+  return profileResolvedDir()
+}
+
+function datedLogFile(prefix: string): string {
+  const d = new Date()
+  const pad = (n: number) => String(n).padStart(2, "0")
+  return `oes-${prefix}-${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}.log`
+}
+
+let _dir: string | null | undefined = undefined // undefined = not resolved yet
+let _pdir: string | null | undefined = undefined
+
+function resolvedDir(): string | null {
+  if (_dir !== undefined) return _dir
+  _dir = debugLogDir()
+  if (_dir) {
+    try {
+      fs.mkdirSync(_dir, { recursive: true })
+    } catch {
+      _dir = null
+    }
+  }
+  return _dir
+}
+
+function profileResolvedDir(): string | null {
+  if (_pdir !== undefined) return _pdir
+  _pdir = profileLogDir()
+  if (_pdir) {
+    try {
+      fs.mkdirSync(_pdir, { recursive: true })
+    } catch {
+      _pdir = null
+    }
+  }
+  return _pdir
+}
+
+/** Reset cached state (test helper). */
+export function resetDebug(): void {
+  _dir = undefined
+  _pdir = undefined
+  profileStats = {}
+  screenLines = []
+}
+
+/** One on-screen console line: a timestamp plus a short label (e.g. `db open`). */
+export type ScreenLine = { at: number; text: string }
+
+/** Ring cap — the console shows a 5-line window over these, scrolled. */
+const SCREEN_MAX = 200
+
+let screenLines: ScreenLine[] = []
+const screenListeners = new Set<() => void>()
+
+/**
+ * Append one short label (e.g. `db open`) to the sidebar console's screen ring
+ * and notify subscribers. No-op unless a debug or profile logger is active, so
+ * a normal session pays nothing for it.
+ */
+export function pushScreenLine(text: string): void {
+  if (!debugActive() && !profileActive()) return
+  screenLines.push({ at: Date.now(), text })
+  if (screenLines.length > SCREEN_MAX) screenLines.splice(0, screenLines.length - SCREEN_MAX)
+  for (const listener of screenListeners) {
+    try {
+      listener()
+    } catch {
+      // a subscriber must never break the ring feed
+    }
+  }
+}
+
+/** Newest-first copy of the screen ring (empty when nothing was pushed). */
+export function readScreenLines(): ScreenLine[] {
+  return screenLines.slice().reverse()
+}
+
+/** Subscribe to screen-ring pushes; returns an unsubscribe fn. */
+export function subscribeScreenLines(listener: () => void): () => void {
+  screenListeners.add(listener)
+  return () => {
+    screenListeners.delete(listener)
+  }
+}
+
+function appendLine(dir: string, file: string, line: Record<string, unknown>): void {
+  try {
+    const entry = { ts: new Date().toISOString(), ...line }
+    fs.appendFileSync(path.join(dir, file), JSON.stringify(entry) + "\n", "utf8")
+  } catch {
+    // silent — logging must never crash the plugin
+  }
+}
+
+/**
+ * Append one JSON-line entry to the debug log.
+ * No-op when OES_DEBUG_OPENCODE is not set or falsy.
+ */
+export function dbg(tag: string, msg: string, data?: unknown): void {
+  const dir = resolvedDir()
+  if (!dir) return
+  appendLine(dir, datedLogFile("debug"), {
+    tag,
+    msg,
+    ...(data !== undefined ? { data } : {}),
+  })
+}
+
+export type ProfileStats = { n: number; sum: number; max: number }
+
+/** In-memory per-tag totals, updated only while OES_DEBUG_PROFILE is on. */
+let profileStats: Record<string, ProfileStats> = {}
+
+/** Lazily-computed or plain profile data — a factory keeps the call site free when off. */
+type ProfileData = Record<string, unknown> | (() => Record<string, unknown>)
+
+function resolveData(data: ProfileData | undefined): Record<string, unknown> | undefined {
+  const d = typeof data === "function" ? data() : data
+  return d && Object.keys(d).length > 0 ? d : undefined
+}
+
+function recordProfile(tag: string, ms: number, data?: ProfileData): void {
+  const dir = profileResolvedDir()
+  if (!dir) return
+  const s = (profileStats[tag] ??= { n: 0, sum: 0, max: 0 })
+  s.n += 1
+  s.sum += ms
+  if (ms > s.max) s.max = ms
+  const d = resolveData(data)
+  appendLine(dir, datedLogFile("profile"), {
+    tag,
+    ms,
+    ...(d !== undefined ? { data: d } : {}),
+  })
+}
+
+/**
+ * Measure fn with performance.now() and append one { tag, ms, data? } line to
+ * the profile log. No-op when OES_DEBUG_PROFILE is not set or falsy. Returns
+ * fn's result; throws propagate.
+ */
+export function profile<T>(tag: string, fn: () => T, data?: ProfileData): T {
+  if (!profileResolvedDir()) return fn()
+  const t0 = performance.now()
+  try {
+    return fn()
+  } finally {
+    recordProfile(tag, performance.now() - t0, data)
+  }
+}
+
+/**
+ * Same as profile(), but for an async fn — measures until the returned promise
+ * settles. The fn is invoked immediately (the promise is what is timed).
+ */
+export function profileAsync<T>(
+  tag: string,
+  fn: () => Promise<T>,
+  data?: ProfileData,
+): Promise<T> {
+  if (!profileResolvedDir()) return fn()
+  const t0 = performance.now()
+  return fn().then(
+    (value) => {
+      recordProfile(tag, performance.now() - t0, data)
+      return value
+    },
+    (err) => {
+      recordProfile(tag, performance.now() - t0, data)
+      throw err
+    },
+  )
+}
+
+/** Shallow copy of the per-tag profile totals. Empty when profiling is off. */
+export function readProfileStats(): Record<string, ProfileStats> {
+  const out: Record<string, ProfileStats> = {}
+  for (const [tag, s] of Object.entries(profileStats)) out[tag] = { ...s }
+  return out
+}
+
+/**
+ * Append one `summary` line with the per-tag totals (n, total ms, avg, max) to
+ * the profile log. No-op when profiling is off or nothing was measured.
+ */
+export function writeProfileSummary(): void {
+  const dir = profileResolvedDir()
+  if (!dir) return
+  const stats = readProfileStats()
+  const tags = Object.keys(stats)
+  if (tags.length === 0) return
+  const summary: Record<string, { n: number; total: number; avg: number; max: number }> = {}
+  for (const tag of tags) {
+    const s = stats[tag]
+    summary[tag] = {
+      n: s.n,
+      total: Math.round(s.sum * 10) / 10,
+      avg: Math.round((s.sum / s.n) * 10) / 10,
+      max: Math.round(s.max * 10) / 10,
+    }
+  }
+  appendLine(dir, datedLogFile("profile"), { tag: "summary", data: summary })
+}

package/src/pware.oc.core/pware.oc.core.events.ts

@@ -0,0 +1,79 @@
+/** Host event type + kind. Never reads request or response bodies. */
+import {
+  EVENT_FILE_EDITED,
+  EVENT_MESSAGE_PART_UPDATED,
+  EVENT_PART_DELTA,
+  EVENT_REASONING_DELTA,
+  EVENT_REASONING_STARTED,
+  EVENT_SESSION_CREATED,
+  EVENT_SESSION_DIFF,
+  EVENT_SESSION_IDLE,
+  EVENT_SESSION_STATUS,
+  EVENT_SESSION_UPDATED,
+  EVENT_STEP_ENDED,
+  EVENT_STEP_FAILED,
+  EVENT_STEP_STARTED,
+  EVENT_TEXT_DELTA,
+  EVENT_TOOL_CALLED,
+  EVENT_TOOL_ENDED,
+  EVENT_TOOL_FAILED,
+  EVENT_TOOL_SUCCESS,
+} from "./constants/pware.oc.core.constants.eventType.js"
+
+import {
+  EVENT_KIND_DB_REFRESH,
+  EVENT_KIND_FILE,
+  EVENT_KIND_FLOW,
+  EVENT_KIND_TOOL,
+  type EventKind,
+} from "./constants/pware.oc.core.constants.eventKind.js"
+
+export type { EventKind }
+
+export function eventType(evt: unknown): string {
+  if (!evt || typeof evt !== "object") return ""
+  return String((evt as Record<string, unknown>).type ?? "").toLowerCase()
+}
+
+export function eventKind(type: string): EventKind | null {
+  const t = (type || "").toLowerCase()
+  if (!t) return null
+  if (t.includes(EVENT_FILE_EDITED) || t.includes(EVENT_SESSION_DIFF)) return EVENT_KIND_FILE
+  if (
+    t.includes(EVENT_TOOL_CALLED) ||
+    t.includes(EVENT_TOOL_SUCCESS) ||
+    t.includes(EVENT_TOOL_FAILED) ||
+    t.includes(EVENT_TOOL_ENDED)
+  ) {
+    return EVENT_KIND_TOOL
+  }
+  if (
+    t.includes(EVENT_SESSION_STATUS) ||
+    t.includes(EVENT_SESSION_IDLE) ||
+    t.includes(EVENT_SESSION_CREATED) ||
+    t.includes(EVENT_SESSION_UPDATED) ||
+    t.includes(EVENT_MESSAGE_PART_UPDATED) ||
+    t.includes(EVENT_STEP_STARTED) ||
+    t.includes(EVENT_STEP_ENDED) ||
+    t.includes(EVENT_STEP_FAILED)
+  ) {
+    return EVENT_KIND_DB_REFRESH
+  }
+  if (
+    t.includes(EVENT_TEXT_DELTA) ||
+    t.includes(EVENT_REASONING_DELTA) ||
+    t.includes(EVENT_REASONING_STARTED) ||
+    t.includes(EVENT_PART_DELTA) ||
+    t.endsWith(".delta")
+  ) {
+    return EVENT_KIND_FLOW
+  }
+  return null
+}
+
+export function shouldRefreshDb(type: string): boolean {
+  const t = (type || "").toLowerCase()
+  if (!t || t.includes(".delta")) return false
+  const kind = eventKind(t)
+  return kind === EVENT_KIND_TOOL || kind === EVENT_KIND_FILE || kind === EVENT_KIND_DB_REFRESH
+}

package/src/pware.oc.core/pware.oc.core.glyph.ts

@@ -0,0 +1,135 @@
+/**
+ * pware.oc.core.glyph
+ *
+ * Every visual glyph as one complete definition: a character plus a semantic
+ * tone (and an optional blink flag). A glyph's char and colour can never drift
+ * apart because they come from the same switch. `markTone` / `stateGlyph` /
+ * `directionGlyph` are pure and theme-independent — the ui layer resolves a
+ * `ToneKey` to an actual RGBA through `toneColor` in
+ * `pware.oc.ui/pware.oc.ui.chrome.tsx`.
+ */
+import { BLINK_TICKS } from "./pware.oc.core.timing.js"
+import {
+  FLOW_RECV,
+  FLOW_TOOL,
+  FLOW_WAIT,
+  MARK_QUEUED,
+  PULSE_LIVE,
+  PULSE_STALE,
+  type AgentMark,
+  type FlowDir,
+} from "./constants/pware.oc.core.constants.pulse.js"
+import { STATUS_ERROR } from "./constants/pware.oc.core.constants.status.js"
+import {
+  ROW_KIND_FILE,
+  ROW_KIND_GROUP,
+  type RowKind,
+} from "./constants/pware.oc.core.constants.rowKind.js"
+
+/** Semantic colour of a glyph or body — no theme values, just meaning. */
+export type ToneKey = "text" | "textMuted" | "success" | "primary" | "warning" | "error"
+
+/** One glyph as a complete definition: the character, its tone, and blink. */
+export type GlyphSpec = {
+  char: string
+  tone: ToneKey
+  blink?: boolean
+}
+
+/** Same braille set as OpenCode TUI thinking spinner (`opentui-spinner`). */
+export const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const
+
+/** Queued — waiting for a slot: the hourglass (the wait flow owns ◷). */
+export const QUEUED_GLYPH = "⧗"
+
+export function spinnerFrame(frame: number): string {
+  const i = ((frame % SPINNER_FRAMES.length) + SPINNER_FRAMES.length) % SPINNER_FRAMES.length
+  return SPINNER_FRAMES[i] ?? "⠋"
+}
+
+/** Cold-start "engage" bar length in glyph frames (GLYPH_TICK_MS × 12 ≈ 1s). */
+export const ENGAGE_MIN_FRAMES = 12
+/** Hard ceiling so the boot bar can never strand (GLYPH_TICK_MS × 50 = 4s). */
+export const ENGAGE_MAX_FRAMES = 50
+
+/** Fill ratio of the cold-start engage bar: linear to 1 at `ENGAGE_MIN_FRAMES`. */
+export function engageFill(frame: number): number {
+  return Math.min(1, Math.max(0, frame) / ENGAGE_MIN_FRAMES)
+}
+
+/**
+ * The cold-start engage bar ends once the first real snapshot has landed
+ * (`ready`) after its minimum show time — or on the hard ceiling (no DB / no
+ * snapshot ever) so the row can never strand. Negative frames count as 0.
+ */
+export function engageDone(frame: number, ready: boolean): boolean {
+  const n = Math.max(0, frame)
+  return (ready && n >= ENGAGE_MIN_FRAMES) || n >= ENGAGE_MAX_FRAMES
+}
+
+/** Options for {@link sinPulseAlpha} — one full fade cycle spans `periodFrames` tick frames. */
+export type SinPulseAlphaOpts = {
+  periodFrames?: number
+  min?: number
+  max?: number
+}
+
+/**
+ * Sinusoidal fade pulse for glyph opacity: alpha eases `min → max → min` over one
+ * period. Defaults to `BLINK_TICKS * 2` frames (same wall-clock span as
+ * {@link flowBlinkOn}). Pure — inject the UI tick frame; the ui layer maps the
+ * result to OpenTUI `opacity` or a colour lerp.
+ */
+export function sinPulseAlpha(frame: number, opts: SinPulseAlphaOpts = {}): number {
+  const period = Math.max(1, Math.round(opts.periodFrames ?? BLINK_TICKS * 2))
+  const lo = Math.min(opts.min ?? 0.25, opts.max ?? 1)
+  const hi = Math.max(opts.min ?? 0.25, opts.max ?? 1)
+  const phase = (Math.abs(frame) % period) / period
+  const wave = Math.sin(phase * Math.PI)
+  return lo + wave * (hi - lo)
+}
+
+/** ↑/↓ blink half-period in ticks (TICK_MS × BLINK_TICKS = 100ms). */
+export function flowBlinkOn(frame: number): boolean {
+  return Math.floor(Math.abs(frame) / BLINK_TICKS) % 2 === 0
+}
+
+/** The tone a state mark carries: error red, queued/stale warning, live success, else muted. */
+export function markTone(mark: AgentMark): ToneKey {
+  if (mark === STATUS_ERROR) return "error"
+  if (mark === MARK_QUEUED || mark === PULSE_STALE) return "warning"
+  if (mark === PULSE_LIVE) return "success"
+  return "textMuted"
+}
+
+/** The state glyph for an agent mark — spinner, cross, hourglass or dot, in one spec. */
+export function stateGlyph(mark: AgentMark, frame = 0): GlyphSpec {
+  const char =
+    mark === STATUS_ERROR
+      ? "×"
+      : mark === MARK_QUEUED
+        ? QUEUED_GLYPH
+        : mark === PULSE_LIVE || mark === PULSE_STALE
+          ? spinnerFrame(frame)
+          : "•"
+  return { char, tone: markTone(mark) }
+}
+
+/** The direction glyph for a flow — ◷ waiting, ← receiving, → tool; null when quiet. */
+export function directionGlyph(flow: FlowDir | null): GlyphSpec | null {
+  if (!flow) return null
+  if (flow === FLOW_WAIT) return { char: "◷", tone: "warning", blink: true }
+  if (flow === FLOW_RECV) return { char: "←", tone: "success", blink: true }
+  return { char: "→", tone: "primary", blink: true }
+}
+
+/** Body text tone for a row kind: quiet for files/groups, otherwise the mark tone. */
+export function defaultBodyTone(
+  kind: RowKind,
+  mark: AgentMark | undefined,
+  current: boolean,
+): ToneKey {
+  if (kind === ROW_KIND_FILE || kind === ROW_KIND_GROUP) return "textMuted"
+  const tone = mark ? markTone(mark) : "textMuted"
+  return current && tone === "textMuted" ? "primary" : tone
+}