opencode-beans 0.0.0-stage → 0.1.0

package/.opencode/plugins/beans-stats/beans.ts

@@ -0,0 +1,133 @@
+import { execFile } from "node:child_process"
+import { promisify } from "node:util"
+import type { Stats } from "./layout.ts"
+
+const run = promisify(execFile)
+const MAX_BUFFER = 8 * 1024 * 1024
+
+export const DEFAULT_TIMEOUT_MS = 5_000
+
+export interface LoadOptions {
+  readonly signal?: AbortSignal
+  readonly timeoutMs?: number
+}
+
+export interface ExecOptions {
+  readonly cwd: string
+  readonly maxBuffer: number
+  readonly timeout: number
+  readonly signal?: AbortSignal
+}
+
+export interface ExecResult {
+  readonly stdout: string
+}
+
+export type ExecFile = (
+  command: string,
+  args: readonly string[],
+  options: ExecOptions,
+) => Promise<ExecResult>
+
+export interface BeanRecord {
+  readonly status: string
+  readonly type?: string
+}
+
+export class BeansUnavailableError extends Error {}
+
+export function parseBeans(raw: string): BeanRecord[] {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new BeansUnavailableError("beans list --json did not return JSON")
+  }
+  if (!Array.isArray(parsed)) {
+    throw new BeansUnavailableError("beans list --json did not return an array")
+  }
+  return parsed.map((entry) => {
+    const record = entry as { status?: unknown; type?: unknown } | null
+    const status = record?.status
+    if (typeof status !== "string") {
+      throw new BeansUnavailableError("a bean is missing its status")
+    }
+    const type = record?.type
+    return typeof type === "string" ? { status, type } : { status }
+  })
+}
+
+export function aggregate(
+  beans: readonly BeanRecord[],
+  ready?: number,
+  blocked?: number,
+): Stats {
+  const counts = new Map<string, number>()
+  const types = new Map<string, number>()
+  for (const bean of beans) {
+    counts.set(bean.status, (counts.get(bean.status) ?? 0) + 1)
+    if (bean.type !== undefined) {
+      types.set(bean.type, (types.get(bean.type) ?? 0) + 1)
+    }
+  }
+  return {
+    total: beans.length,
+    byStatus: [...counts].map(([status, count]) => ({ status, count })),
+    byType: [...types].map(([type, count]) => ({ type, count })),
+    ...(ready === undefined ? {} : { ready }),
+    ...(blocked === undefined ? {} : { blocked }),
+  }
+}
+
+export interface BeanReader {
+  loadStats(dir: string, options?: LoadOptions): Promise<Stats>
+}
+
+export function createBeanReader(exec: ExecFile): BeanReader {
+  const list = async (
+    dir: string,
+    args: string[],
+    options: LoadOptions,
+  ): Promise<BeanRecord[]> => {
+    const { stdout } = await exec("beans", args, {
+      cwd: dir,
+      maxBuffer: MAX_BUFFER,
+      timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+    })
+    return parseBeans(stdout)
+  }
+
+  const count = async (
+    dir: string,
+    args: string[],
+    options: LoadOptions,
+  ): Promise<number | undefined> => {
+    try {
+      return (await list(dir, args, options)).length
+    } catch {
+      return undefined
+    }
+  }
+
+  return {
+    async loadStats(dir: string, options: LoadOptions = {}): Promise<Stats> {
+      let beans: BeanRecord[]
+      try {
+        beans = await list(dir, ["list", "--json"], options)
+      } catch {
+        throw new BeansUnavailableError("beans list --json failed")
+      }
+      const ready = await count(dir, ["list", "--ready", "--json"], options)
+      const blocked = await count(dir, ["list", "--is-blocked", "--json"], options)
+      return aggregate(beans, ready, blocked)
+    },
+  }
+}
+
+const defaultExec: ExecFile = async (command, args, options) => {
+  const { stdout } = await run(command, [...args], { ...options })
+  return { stdout }
+}
+
+export const { loadStats } = createBeanReader(defaultExec)

package/.opencode/plugins/beans-stats/cache.ts

@@ -0,0 +1,104 @@
+import type { Stats, StatusCount, TypeCount } from "./layout.ts"
+
+export const CACHE_KEY = "beans.stats.cache"
+
+export interface CacheState {
+  [directory: string]: Stats
+}
+
+function decodeCount(entry: unknown): StatusCount | null {
+  if (typeof entry !== "object" || entry === null) {
+    return null
+  }
+  const record = entry as { status?: unknown; count?: unknown }
+  if (typeof record.status !== "string" || typeof record.count !== "number") {
+    return null
+  }
+  return { status: record.status, count: record.count }
+}
+
+function decodeType(entry: unknown): TypeCount | null {
+  if (typeof entry !== "object" || entry === null) {
+    return null
+  }
+  const record = entry as { type?: unknown; count?: unknown }
+  if (typeof record.type !== "string" || typeof record.count !== "number") {
+    return null
+  }
+  return { type: record.type, count: record.count }
+}
+
+export function decodeStats(raw: unknown): Stats | null {
+  if (typeof raw !== "object" || raw === null) {
+    return null
+  }
+  const record = raw as {
+    total?: unknown
+    byStatus?: unknown
+    byType?: unknown
+    ready?: unknown
+    blocked?: unknown
+  }
+  if (typeof record.total !== "number" || !Array.isArray(record.byStatus)) {
+    return null
+  }
+  const byStatus: StatusCount[] = []
+  for (const entry of record.byStatus) {
+    const decoded = decodeCount(entry)
+    if (decoded === null) {
+      return null
+    }
+    byStatus.push(decoded)
+  }
+  const byType: TypeCount[] = []
+  if (record.byType !== undefined) {
+    if (!Array.isArray(record.byType)) {
+      return null
+    }
+    for (const entry of record.byType) {
+      const decoded = decodeType(entry)
+      if (decoded === null) {
+        return null
+      }
+      byType.push(decoded)
+    }
+  }
+  return {
+    total: record.total,
+    byStatus,
+    byType,
+    ...(typeof record.ready === "number" ? { ready: record.ready } : {}),
+    ...(typeof record.blocked === "number" ? { blocked: record.blocked } : {}),
+  }
+}
+
+export function toSnapshot(stats: Stats): Stats {
+  return {
+    total: stats.total,
+    byStatus: stats.byStatus.map((entry) => ({ status: entry.status, count: entry.count })),
+    byType: (stats.byType ?? []).map((entry) => ({ type: entry.type, count: entry.count })),
+    ...(stats.ready === undefined ? {} : { ready: stats.ready }),
+    ...(stats.blocked === undefined ? {} : { blocked: stats.blocked }),
+  }
+}
+
+export interface CachePort {
+  read(directory: string): unknown
+  write(directory: string, stats: Stats): void
+}
+
+export interface Cache {
+  seed(): Stats | null
+  save(stats: Stats): void
+}
+
+export function createCache(port: CachePort, directory: string): Cache {
+  return {
+    seed() {
+      return decodeStats(port.read(directory))
+    },
+    save(stats) {
+      port.write(directory, toSnapshot(stats))
+    },
+  }
+}

package/.opencode/plugins/beans-stats/index.ts

@@ -0,0 +1,6 @@
+import { Plugin } from "@opencode/plugin"
+
+export default Plugin.define({
+  id: "beans.stats",
+  setup() {},
+})

package/.opencode/plugins/beans-stats/layout.ts

@@ -0,0 +1,136 @@
+export interface StatusCount {
+  readonly status: string
+  readonly count: number
+}
+
+export interface TypeCount {
+  readonly type: string
+  readonly count: number
+}
+
+export interface Stats {
+  readonly total: number
+  readonly byStatus: readonly StatusCount[]
+  readonly byType?: readonly TypeCount[]
+  readonly ready?: number
+  readonly blocked?: number
+}
+
+export interface SummaryLine {
+  readonly label: string
+  readonly count: number
+}
+
+export interface SectionLayout {
+  readonly total: string
+  readonly body: readonly string[]
+}
+
+interface Cell {
+  readonly label: string
+  readonly count: number
+  readonly bar?: string
+}
+
+interface ColumnWidths {
+  readonly label: number
+  readonly count: number
+}
+
+const BAR_WIDTH = 4
+const FULL_BLOCK = "█"
+const HALF_BLOCK = "▌"
+const LABEL_GUTTER = 2
+const COUNT_GUTTER = 2
+const BAR_GAP = "  "
+
+export function statusRows(stats: Stats): StatusCount[] {
+  return [...stats.byStatus].sort(
+    (left, right) => right.count - left.count || left.status.localeCompare(right.status),
+  )
+}
+
+export function typeRows(stats: Stats): TypeCount[] {
+  return [...(stats.byType ?? [])].sort(
+    (left, right) => right.count - left.count || left.type.localeCompare(right.type),
+  )
+}
+
+export function bars<T extends { readonly count: number }>(
+  entries: readonly T[],
+  width: number = BAR_WIDTH,
+): Array<T & { readonly bar: string }> {
+  const max = entries.reduce((largest, entry) => Math.max(largest, entry.count), 0)
+  return entries.map((entry) => ({ ...entry, bar: bar(entry.count, max, width) }))
+}
+
+export function bar(count: number, max: number, width: number = BAR_WIDTH): string {
+  if (max <= 0 || count <= 0) {
+    return ""
+  }
+  const steps = Math.min(width * 2, Math.round((count / max) * width * 2))
+  const full = Math.floor(steps / 2)
+  const half = steps % 2 === 1
+  return FULL_BLOCK.repeat(full) + (half ? HALF_BLOCK : "")
+}
+
+export function totalLabel(stats: Stats): string {
+  return `${stats.total} total`
+}
+
+export function layoutSection(stats: Stats): SectionLayout {
+  return layout(stats, false)
+}
+
+export function layoutBreakdown(stats: Stats): SectionLayout {
+  return layout(stats, true)
+}
+
+function layout(stats: Stats, withTypes: boolean): SectionLayout {
+  const statuses = bars(statusRows(stats)).map((row) => ({
+    label: row.status,
+    count: row.count,
+    bar: row.bar,
+  }))
+  const summary = summaryLines(stats).map((line) => ({ label: line.label, count: line.count }))
+  const types = bars(typeRows(stats)).map((row) => ({ label: row.type, count: row.count, bar: row.bar }))
+  const widths = columnWidths(withTypes ? [...statuses, ...summary, ...types] : [...statuses, ...summary])
+
+  const body: string[] = []
+  appendBlock(body, statuses, widths)
+  appendBlock(body, summary, widths)
+  if (withTypes) {
+    appendBlock(body, types, widths)
+  }
+  return { total: totalLabel(stats), body }
+}
+
+function appendBlock(body: string[], cells: readonly Cell[], widths: ColumnWidths): void {
+  if (cells.length === 0) {
+    return
+  }
+  body.push("", ...cells.map((cell) => renderCell(cell, widths)))
+}
+
+function columnWidths(cells: readonly Cell[]): ColumnWidths {
+  const label = cells.reduce((width, cell) => Math.max(width, cell.label.length), 0) + LABEL_GUTTER
+  const count = cells.reduce((width, cell) => Math.max(width, String(cell.count).length), 0) + COUNT_GUTTER
+  return { label, count }
+}
+
+function renderCell(cell: Cell, widths: ColumnWidths): string {
+  const label = cell.label.padEnd(widths.label)
+  const count = String(cell.count).padStart(widths.count)
+  return cell.bar ? label + count + BAR_GAP + cell.bar : label + count
+}
+
+export function summaryLines(stats: Stats): SummaryLine[] {
+  const lines: SummaryLine[] = []
+  if (stats.ready !== undefined) {
+    lines.push({ label: "ready", count: stats.ready })
+  }
+  if (stats.blocked !== undefined) {
+    lines.push({ label: "blocked", count: stats.blocked })
+  }
+  return lines
+}

package/.opencode/plugins/beans-stats/refresh.ts

@@ -0,0 +1,49 @@
+export interface RefresherOptions<Value> {
+  readonly load: (signal: AbortSignal) => Promise<Value>
+  readonly onValue: (value: Value) => void
+  readonly onError: () => void
+}
+
+export interface Refresher {
+  refresh(): Promise<void>
+  dispose(): void
+}
+
+export function createRefresher<Value>(options: RefresherOptions<Value>): Refresher {
+  let current: AbortController | null = null
+  let disposed = false
+
+  const settle = (controller: AbortController) => {
+    if (current === controller) {
+      current = null
+    }
+  }
+
+  return {
+    async refresh() {
+      if (disposed) {
+        return
+      }
+      current?.abort()
+      const controller = new AbortController()
+      current = controller
+      try {
+        const value = await options.load(controller.signal)
+        if (!controller.signal.aborted) {
+          options.onValue(value)
+        }
+      } catch {
+        if (!controller.signal.aborted) {
+          options.onError()
+        }
+      } finally {
+        settle(controller)
+      }
+    },
+    dispose() {
+      disposed = true
+      current?.abort()
+      current = null
+    },
+  }
+}

package/.opencode/plugins/beans-stats/setup.ts

@@ -0,0 +1,65 @@
+export interface DisposableBag {
+  add(dispose: () => void): void
+  dispose(): void
+}
+
+export function createDisposables(): DisposableBag {
+  const pending: Array<() => void> = []
+  let disposed = false
+
+  return {
+    add(dispose) {
+      if (disposed) {
+        dispose()
+        return
+      }
+      pending.push(dispose)
+    },
+    dispose() {
+      if (disposed) {
+        return
+      }
+      disposed = true
+      while (pending.length > 0) {
+        pending.pop()?.()
+      }
+    },
+  }
+}
+
+export interface SlotHost<Claim> {
+  readonly ui: {
+    readonly slot: (claim: Claim) => () => void
+  }
+}
+
+export function registerSidebar<Claim>(host: SlotHost<Claim>, claim: Claim): () => void {
+  const unregister = host.ui.slot(claim)
+  return () => unregister()
+}
+
+export const PANEL_NAME = "beans-stats"
+export const PANEL_COMMAND_ID = "beans.stats.panel"
+export const PANEL_BIND = "<leader>d"
+
+export interface PanelCommand {
+  readonly id: string
+  readonly title: string
+  readonly description: string
+  readonly group: string
+  readonly bind: string
+  readonly run: () => void
+}
+
+export function panelCommand(open: (name: string) => unknown): PanelCommand {
+  return {
+    id: PANEL_COMMAND_ID,
+    title: "Beans breakdown",
+    description: "Show the full beans breakdown panel",
+    group: "Beans",
+    bind: PANEL_BIND,
+    run: () => {
+      open(PANEL_NAME)
+    },
+  }
+}

package/.opencode/plugins/beans-stats/tui.tsx

@@ -0,0 +1,135 @@
+import { For, Index, Show, createSignal, type Accessor } from "solid-js"
+import { Plugin, usePlugin } from "@opencode/plugin/tui"
+import {
+  layoutBreakdown,
+  layoutSection,
+  type SectionLayout,
+  type Stats,
+} from "./layout.ts"
+import { PANEL_NAME, createDisposables, panelCommand, registerSidebar } from "./setup.ts"
+import { loadStats } from "./beans.ts"
+import { createRefresher } from "./refresh.ts"
+import { CACHE_KEY, createCache, type CacheState } from "./cache.ts"
+
+function BeansLines(props: {
+  readonly stats: Accessor<Stats | null>
+  readonly error: Accessor<string | null>
+  readonly layout: (stats: Stats) => SectionLayout
+}) {
+  const context = usePlugin()
+  return (
+    <Show
+      when={props.stats()}
+      fallback={<text fg={context.theme.text.muted}>{props.error() ?? "loading"}</text>}
+    >
+      {(stats: Accessor<Stats>) => (
+        <>
+          <text fg={context.theme.text.base}>{props.layout(stats()).total}</text>
+          <Index each={props.layout(stats()).body}>
+            {(line) => <text fg={context.theme.text.muted}>{line()}</text>}
+          </Index>
+        </>
+      )}
+    </Show>
+  )
+}
+
+function BeansStats(props: {
+  readonly stats: Accessor<Stats | null>
+  readonly error: Accessor<string | null>
+}) {
+  const context = usePlugin()
+  return (
+    <box flexDirection="column" gap={0}>
+      <text fg={context.theme.text.muted}>BEANS</text>
+      <BeansLines stats={props.stats} error={props.error} layout={layoutSection} />
+    </box>
+  )
+}
+
+function BeansBreakdown(props: {
+  readonly stats: Accessor<Stats | null>
+  readonly error: Accessor<string | null>
+}) {
+  const context = usePlugin()
+  return (
+    <box flexDirection="column" gap={0}>
+      <text fg={context.theme.text.muted}>BEANS</text>
+      <BeansLines stats={props.stats} error={props.error} layout={layoutBreakdown} />
+    </box>
+  )
+}
+
+export default Plugin.define({
+  id: "beans.stats",
+  setup(context) {
+    const [stats, setStats] = createSignal<Stats | null>(null)
+    const [error, setError] = createSignal<string | null>(null)
+    const bag = createDisposables()
+    const dir = () => (context.location ?? context.data.location.default()).directory
+
+    const [cacheState, updateCache] = context.storage.store<CacheState>(CACHE_KEY, { initial: {} })
+    const cache = createCache(
+      {
+        read: (directory) => cacheState[directory],
+        write: (directory, value) => {
+          void updateCache((draft) => {
+            draft[directory] = value
+          })
+        },
+      },
+      dir(),
+    )
+
+    const cached = cache.seed()
+    if (cached !== null) {
+      setStats(cached)
+    }
+
+    const refresher = createRefresher<Stats>({
+      load: (signal) => loadStats(dir(), { signal }),
+      onValue: (value) => {
+        setStats(value)
+        setError(null)
+        cache.save(value)
+      },
+      onError: () => {
+        setStats(null)
+        setError("unavailable")
+      },
+    })
+
+    void refresher.refresh()
+
+    bag.add(context.data.on("session.execution.succeeded", () => void refresher.refresh()))
+
+    const timer = setInterval(() => void refresher.refresh(), 30_000)
+    bag.add(() => clearInterval(timer))
+
+    bag.add(refresher.dispose)
+
+    bag.add(
+      registerSidebar(context, {
+        append: "sidebar.content",
+        render: () => <BeansStats stats={stats} error={error} />,
+      }),
+    )
+
+    bag.add(
+      registerSidebar(context, {
+        append: "session.panel",
+        render: (input) => (
+          <Show when={input.name === PANEL_NAME}>
+            <BeansBreakdown stats={stats} error={error} />
+          </Show>
+        ),
+      }),
+    )
+
+    context.keymap.layer(() => ({
+      commands: [panelCommand((name) => context.ui.panel.open(name))],
+    }))
+
+    return () => bag.dispose()
+  },
+})

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pim Snel
+
+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,91 @@
-# Temporary Holding Version
+# opencode-beans
 
-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 v2 plugin that shows [Beans](https://github.com/hmans/beans) issue
+statistics in the sidebar of the OpenCode TUI.
+
+```
+BEANS
+42 total
+
+todo           18  ████
+in-progress     6  █▌
+completed       2  ▌
+
+ready          11
+blocked         3
+```
+
+The section refreshes after every assistant turn and on a fallback timer. When
+`.beans/` is missing or `beans` fails it shows a muted `unavailable` line
+instead of crashing.
+
+The last counts are cached per project, so a project that has been read before
+paints its counts immediately on startup. The full breakdown, including the
+per-type split, opens in a session panel from a command bound to `<leader>d`.
+
+## Prerequisites
+
+`beans`, `openspec` and `jj` must be on `PATH`. Everything else comes from the
+nix flake.
+
+## Install
+
+The plugin is discovered automatically from a project's
+`.opencode/plugins/<name>/` directory. To use it in a project:
+
+1. Make sure that project has been initialized with `beans init`, so `.beans/`
+   and `.beans.yml` exist at its root.
+2. Copy the plugin directory into the project:
+
+   ```bash
+   mkdir -p .opencode/plugins
+   cp -r /path/to/opencode-beans/.opencode/plugins/beans-stats .opencode/plugins/
+   ```
+
+3. Start OpenCode in that project. Confirm the plugin loaded:
+
+   ```bash
+   opencode plugin list
+   ```
+
+The assembled plugin is also available from `nix build`, see [Build](#build).
+
+## Development
+
+```bash
+nix develop          # working environment: Node 24, python3, jujutsu, nixfmt
+npm install          # dependencies for the tests and the type check
+```
+
+## Testing
+
+```bash
+npm test             # unit and integration tests
+npm run test:e2e     # end to end tests against the real OpenCode terminal
+npm run typecheck    # TypeScript
+nix flake check      # unit and integration tests in a pure sandbox
+```
+
+The unit tests are pure logic. The integration tests run the real `beans` CLI
+against a temporary fixture project and skip when `beans` is not available. The
+end to end tests boot OpenCode against a fixture project in a pseudo terminal
+and assert the rendered sidebar; they skip when their prerequisites are absent.
+See `e2e/README.md` for the harness.
+
+## Build
+
+```bash
+nix build
+```
+
+The plugin files are then at `result/plugins/beans-stats/` (`index.ts`,
+`tui.tsx`, `beans.ts`, `cache.ts`, `layout.ts`, `refresh.ts`, `setup.ts`).
+
+## How work is organised
+
+- Milestones and epics: beans. Milestone titles start with `01`, `02`, ...
+- Epic internals: OpenSpec. One change per epic.
+- Version control: jj, committed as Pim Snel.
+
+See `AGENTS.md` for the full operating manual and `BRIEFING.md` for the product
+goal.

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "opencode-beans",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Beans stats sidebar plugin for OpenCode v2",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mipmip/opencode-beans.git"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "beans"
+  ],
+  "exports": {
+    ".": "./.opencode/plugins/beans-stats/index.ts",
+    "./tui": "./.opencode/plugins/beans-stats/tui.tsx"
+  },
+  "files": [
+    ".opencode/plugins/beans-stats"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test \"tests/**/*.test.ts\"",
+    "test:e2e": "node --test \"e2e/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@opencode/plugin": "^2.0.31"
+  },
+  "peerDependencies": {
+    "@opentui/core": ">=0.6.6",
+    "@opentui/solid": ">=0.6.6",
+    "solid-js": ">=1.9.0"
+  },
+  "devDependencies": {
+    "@opentui/core": ">=0.6.6",
+    "@opentui/solid": ">=0.6.6",
+    "@types/node": "^24",
+    "solid-js": "^1.9.0",
+    "typescript": "^5"
+  }
+}