@hacky.software/opencode-todo-supervisor 0.0.0-stage → 0.3.1

package/src/panel.ts

@@ -0,0 +1,289 @@
+// todo-supervisor — pure presentation helpers for the TUI todo panel (§6, aspect 12).
+//
+// Everything here is framework-free: layout math, row building, cursor movement
+// and truncation are unit-tested without an OpenTUI renderer. src/tui.tsx only
+// maps these rows to <text>/<box> elements.
+
+export type PanelItem = { content: string; status: string; priority?: string }
+export type PanelFileItem = { content: string; status: string; line?: number }
+export type PanelFile = { path: string; exists: boolean; items: PanelFileItem[] }
+
+/** RPC `list` → `supervisor` payload (see Supervisor.snapshot). */
+export type PanelSupervisor = {
+  registered?: boolean
+  status?: string
+  paused?: boolean
+  pauseReason?: string | null
+  blocked?: number
+  runningChildren?: number
+  runningShells?: number
+  runningTools?: number
+  spans?: string[]
+  quietMs?: number
+  terminal?: boolean
+  nudges?: number
+  noProgress?: number
+}
+
+export type PanelSnapshot = {
+  items: PanelItem[]
+  files: PanelFile[]
+  supervisor?: PanelSupervisor
+}
+
+export type Row =
+  | { kind: "section"; key: string; label: string; detail?: string; muted?: boolean }
+  | {
+      kind: "file"
+      key: string
+      path: string
+      label: string
+      open: number
+      total: number
+      exists: boolean
+      collapsed: boolean
+    }
+  | {
+      kind: "item"
+      key: string
+      source: "session" | "file"
+      content: string
+      status: string
+      priority?: string
+      path?: string
+      line?: number
+      index?: number
+    }
+
+export type ItemRow = Extract<Row, { kind: "item" }>
+export type FileRow = Extract<Row, { kind: "file" }>
+
+export function isSelectable(row: Row): row is ItemRow | FileRow {
+  return row.kind === "item" || row.kind === "file"
+}
+
+/** `[ ]` / `[~]` (in progress or canceled) / `[x]` — matches todo_read. */
+export function statusMark(status: string): string {
+  if (status === "completed") return "[x]"
+  if (status === "in_progress" || status === "canceled") return "[~]"
+  return "[ ]"
+}
+
+export function countOpen(items: readonly { status: string }[]): number {
+  return items.filter((item) => item.status !== "completed").length
+}
+
+/** `████░░░░` filled by completion ratio; `░` when there is nothing to do. */
+export function progressBar(done: number, total: number, width: number): string {
+  const cells = Math.max(0, Math.floor(width))
+  if (cells === 0) return ""
+  if (total <= 0) return "░".repeat(cells)
+  const filled = Math.max(0, Math.min(cells, Math.round((done / total) * cells)))
+  return "█".repeat(filled) + "░".repeat(cells - filled)
+}
+
+/** Single-line, whitespace-collapsed, ellipsised to `width` cells. */
+export function truncate(text: string, width: number): string {
+  const clean = text.replace(/\s+/g, " ").trim()
+  if (width <= 0) return ""
+  if (clean.length <= width) return clean
+  if (width === 1) return "…"
+  return `${clean.slice(0, width - 1)}…`
+}
+
+/** `3s` / `1m20s` — compact quiet-time label. */
+export function quietLabel(ms: number | undefined): string {
+  if (ms === undefined) return "—"
+  const seconds = Math.max(0, Math.round(ms / 1000))
+  if (seconds < 60) return `${seconds}s`
+  return `${Math.floor(seconds / 60)}m${String(seconds % 60).padStart(2, "0")}s`
+}
+
+/** One-line supervision summary for the panel header. */
+export function supervisorChip(supervisor: PanelSupervisor | undefined): string {
+  if (!supervisor || supervisor.registered === false) return "not supervised"
+  const nudges = supervisor.nudges ?? 0
+  if (supervisor.paused) return `paused (${supervisor.pauseReason ?? "paused"}) · nudges ${nudges}`
+  const work: string[] = []
+  const plural = (count: number, one: string) => `${count} ${one}${count === 1 ? "" : "s"}`
+  if (supervisor.runningTools) work.push(plural(supervisor.runningTools, "tool"))
+  if (supervisor.runningChildren) work.push(plural(supervisor.runningChildren, "subagent"))
+  if (supervisor.runningShells) work.push(plural(supervisor.runningShells, "shell"))
+  if (work.length > 0) return `working: ${work.join(" · ")} · quiet ${quietLabel(supervisor.quietMs)}`
+  if (supervisor.terminal === false) return `waiting for turn end · quiet ${quietLabel(supervisor.quietMs)}`
+  return `idle · quiet ${quietLabel(supervisor.quietMs)} · nudges ${nudges}`
+}
+
+export type BuildOptions = {
+  /** Case-insensitive substring filter over item content. */
+  filter?: string
+  /** Collapsed markdown file paths (their items are hidden). */
+  collapsed?: ReadonlySet<string>
+  /** Path display, e.g. `context.ui.format.path` (defaults to identity). */
+  formatPath?: (path: string) => string
+}
+
+function matches(text: string, filter: string): boolean {
+  return filter === "" || text.toLowerCase().includes(filter)
+}
+
+/**
+ * Flatten a snapshot into panel rows: `SESSION` section, then one section per
+ * subscribed file (collapsible), each item selectable. Filters hide items and
+ * whole sections that no longer match; the cursor is kept by row key elsewhere.
+ */
+export function buildRows(snapshot: PanelSnapshot, options: BuildOptions = {}): Row[] {
+  const filter = (options.filter ?? "").trim().toLowerCase()
+  const collapsed = options.collapsed ?? new Set<string>()
+  const formatPath = options.formatPath ?? ((path: string) => path)
+  const rows: Row[] = []
+
+  const sessionVisible = snapshot.items.filter((item) => matches(item.content, filter))
+  if (snapshot.items.length > 0 && sessionVisible.length > 0) {
+    rows.push({
+      kind: "section",
+      key: "section:session",
+      label: "SESSION",
+      detail: `${countOpen(snapshot.items)} open of ${snapshot.items.length}`,
+    })
+    for (const item of sessionVisible) {
+      const index = snapshot.items.indexOf(item)
+      rows.push({
+        kind: "item",
+        key: `session:${index}`,
+        source: "session",
+        index,
+        content: item.content,
+        status: item.status,
+        priority: item.priority,
+      })
+    }
+  }
+
+  for (const file of snapshot.files) {
+    const visible = file.items.filter((item) => matches(item.content, filter))
+    if (filter !== "" && visible.length === 0) continue
+    const isCollapsed = collapsed.has(file.path)
+    rows.push({
+      kind: "file",
+      key: `file:${file.path}`,
+      path: file.path,
+      label: formatPath(file.path),
+      open: countOpen(file.items),
+      total: file.items.length,
+      exists: file.exists,
+      collapsed: isCollapsed,
+    })
+    if (isCollapsed) continue
+    for (const item of visible) {
+      rows.push({
+        kind: "item",
+        key: `file:${file.path}:${item.line ?? item.content}`,
+        source: "file",
+        path: file.path,
+        line: item.line,
+        content: item.content,
+        status: item.status,
+      })
+    }
+  }
+
+  if (rows.length === 0) {
+    rows.push({
+      kind: "section",
+      key: "section:empty",
+      label: snapshot.items.length > 0 || snapshot.files.length > 0 ? "no matches" : "no todos",
+      detail:
+        snapshot.items.length > 0 || snapshot.files.length > 0
+          ? "clear the filter to see everything"
+          : "the agent records todos with todo_write; /todos add <path> subscribes a file",
+      muted: true,
+    })
+  } else if (countOpen(snapshot.items) + snapshot.files.reduce((sum, file) => sum + countOpen(file.items), 0) === 0) {
+    rows.push({ kind: "section", key: "section:done", label: "all todos done 🎉", muted: true })
+  }
+
+  return rows
+}
+
+/** Keeps a row key valid after a refresh; falls back to the first selectable row. */
+export function clampCursor(rows: readonly Row[], key: string | undefined): string | undefined {
+  const selectable = rows.filter(isSelectable)
+  if (selectable.length === 0) return undefined
+  if (key && selectable.some((row) => row.key === key)) return key
+  return selectable[0]!.key
+}
+
+/** Moves by `delta` over selectable rows only, clamped to the ends. */
+export function moveCursor(rows: readonly Row[], key: string | undefined, delta: number): string | undefined {
+  const selectable = rows.filter(isSelectable)
+  if (selectable.length === 0) return undefined
+  const current = selectable.findIndex((row) => row.key === key)
+  const index = current === -1 ? 0 : current
+  const next = Math.max(0, Math.min(selectable.length - 1, index + delta))
+  return selectable[next]!.key
+}
+
+export function rowIndex(rows: readonly Row[], key: string | undefined): number {
+  return key === undefined ? -1 : rows.findIndex((row) => row.key === key)
+}
+
+/** Scroll window that keeps the selected row visible within `height` rows. */
+export function visibleWindow(
+  rows: readonly Row[],
+  key: string | undefined,
+  height: number,
+): { start: number; end: number } {
+  const size = Math.max(1, Math.floor(height))
+  if (rows.length <= size) return { start: 0, end: rows.length }
+  const index = Math.max(0, rowIndex(rows, key))
+  const start = Math.max(0, Math.min(index - Math.floor(size / 2), rows.length - size))
+  return { start, end: start + size }
+}
+
+/** Width-aware key hints for the footer (wide terminals get the long form). */
+export function footerHints(width: number): string[] {
+  const wide = [
+    "↑↓ move",
+    "space toggle",
+    "enter collapse",
+    "n nudge",
+    "s pause",
+    "a add",
+    "d remove",
+    "r refresh",
+    "/ filter",
+    "f size",
+    "c clear",
+    "? help",
+    "esc close",
+  ]
+  if (width >= 120) return wide
+  if (width >= 80) return wide.slice(0, 8)
+  return ["↑↓", "space toggle", "n nudge", "/ filter", "? help", "esc"]
+}
+
+/**
+ * Rows the popover list body may occupy. The dialog hugs its content, so the
+ * body must be bounded or the overlay grows to the whole screen; the cap keeps
+ * it a popover and leaves room for the header and the key legend. `extraRows`
+ * accounts for conditional chrome (e.g. the filter line).
+ */
+export function popoverBodyHeight(viewportHeight: number, extraRows = 0): number {
+  const total = Math.max(10, viewportHeight)
+  return Math.max(4, Math.min(total - 10 - Math.max(0, extraRows), 16))
+}
+
+export type DialogSizeName = "medium" | "large" | "xlarge"
+
+/**
+ * Content width for the popover dialog. The host owns the dialog box, so the
+ * list sizes its rows from the render region instead and clamps for small
+ * terminals (a wider dialog just shows more of each row).
+ */
+export function dialogWidth(size: DialogSizeName, viewportWidth: number): number {
+  const total = Math.max(40, viewportWidth)
+  const bySize =
+    size === "xlarge" ? total - 8 : size === "large" ? total - 16 : Math.min(72, Math.max(48, total - 24))
+  return Math.max(36, Math.min(bySize, 140))
+}

package/src/rpc.test.ts

@@ -0,0 +1,226 @@
+// todo-supervisor — RPC contract + handler unit tests (aspect 11).
+import { describe, expect, test } from "bun:test"
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import type { Plugin } from "@opencode/plugin"
+import { MarkdownCache } from "./markdown"
+import { DEFAULTS, type Options } from "./options"
+import { registerTodoRpc, resolveMarkdownPath, TodoRpc } from "./rpc"
+import type { TodoItem, TodoStore } from "./storage"
+import type { Supervisor } from "./supervisor"
+
+type SubRecord = { version: 1; sessionID: string; files: string[]; removed: string[]; updatedAt: number }
+
+function makeWorld(seedItems: TodoItem[] = []) {
+  const todos = new Map<string, TodoItem[]>([["s1", seedItems]])
+  const subs = new Map<string, SubRecord>()
+  const calls: string[] = []
+  const emitted: { name: string; payload: Record<string, unknown> }[] = []
+
+  const store = {
+    getTodos: (sessionID: string) =>
+      todos.has(sessionID)
+        ? { version: 1 as const, sessionID, items: todos.get(sessionID)!, updatedAt: 0 }
+        : undefined,
+    refreshTodos: async (sessionID: string) =>
+      todos.has(sessionID)
+        ? { version: 1 as const, sessionID, items: todos.get(sessionID)!, updatedAt: 0 }
+        : undefined,
+    setTodos: async (sessionID: string, items: TodoItem[]) => {
+      todos.set(sessionID, items)
+      return { version: 1 as const, sessionID, items, updatedAt: 0 }
+    },
+    removeTodos: async (sessionID: string) => void todos.delete(sessionID),
+    loadSubs: async (sessionID: string) => subs.get(sessionID),
+    setSubs: async (sessionID: string, files: string[], removed: string[]) => {
+      const state: SubRecord = { version: 1, sessionID, files, removed, updatedAt: 0 }
+      subs.set(sessionID, state)
+      return state
+    },
+  } as unknown as TodoStore
+
+  const supervisor = {
+    snapshot: () => ({ registered: true, status: "idle" }),
+    notifyTodosChanged: (sessionID: string) => void calls.push(`changed ${sessionID}`),
+    forceNudge: (sessionID: string) => void calls.push(`nudge ${sessionID}`),
+    setEnabled: (sessionID: string, enabled: boolean) => void calls.push(`enabled ${sessionID} ${enabled}`),
+  } as unknown as Supervisor
+
+  const handlers: Record<string, (input: unknown) => Promise<unknown>> = {}
+  const ctx = {
+    rpc: {
+      register: async (_definition: unknown, registered: typeof handlers) => {
+        Object.assign(handlers, registered)
+        return {
+          events: {
+            emit: async (name: string, payload: Record<string, unknown>) => void emitted.push({ name, payload }),
+          },
+          dispose: async () => {},
+        }
+      },
+    },
+  } as unknown as Plugin.Context
+
+  return { store, supervisor, calls, emitted, handlers, ctx, todos, subs }
+}
+
+async function setup(seedItems: TodoItem[] = [], directory = "/proj", options: Options = DEFAULTS) {
+  const world = makeWorld(seedItems)
+  const logs: string[] = []
+  const reg = await registerTodoRpc(world.ctx, {
+    store: world.store,
+    supervisor: world.supervisor,
+    options,
+    markdown: new MarkdownCache(),
+    directory,
+    log: (...args: unknown[]) => void logs.push(args.map(String).join(" ")),
+  })
+  return { ...world, reg, logs }
+}
+
+describe("RPC contract (§5.6)", () => {
+  test("contract exposes all methods and events", () => {
+    expect(TodoRpc.id).toBe("todo")
+    expect(Object.keys(TodoRpc.methods).sort()).toEqual([
+      "clear",
+      "list",
+      "nudge",
+      "setEnabled",
+      "subscribe",
+      "toggle",
+      "toggleFile",
+      "unsubscribe",
+    ])
+    expect(Object.keys(TodoRpc.events).sort()).toEqual(["nudged", "updated"])
+  })
+
+  test("list returns items, subscriptions placeholder and the supervisor snapshot", async () => {
+    const w = await setup([{ content: "one", status: "pending" }])
+    const result = (await w.handlers.list!({ sessionID: "s1" })) as Record<string, unknown>
+    expect((result.items as TodoItem[]).length).toBe(1)
+    expect(result.files).toEqual([])
+    expect((result.supervisor as Record<string, unknown>).registered).toBe(true)
+  })
+
+  test("clear drops the list, notifies the supervisor and emits updated once", async () => {
+    const w = await setup([{ content: "one", status: "pending" }])
+    await w.handlers.clear!({ sessionID: "s1" })
+    expect(w.todos.has("s1")).toBe(false)
+    expect(w.calls).toContain("changed s1")
+    expect(w.emitted).toEqual([{ name: "updated", payload: { sessionID: "s1" } }])
+  })
+
+  test("nudge and setEnabled delegate to the supervisor", async () => {
+    const w = await setup()
+    await w.handlers.nudge!({ sessionID: "s1" })
+    await w.handlers.setEnabled!({ sessionID: "s1", enabled: false })
+    expect(w.calls).toContain("nudge s1")
+    expect(w.calls).toContain("enabled s1 false")
+  })
+
+  test("subscribe resolves, dedupes and un-shadows; unsubscribe shadows", async () => {
+    const w = await setup()
+    await w.handlers.subscribe!({ sessionID: "s1", path: "docs/TASKS.md" })
+    expect(w.subs.get("s1")!.files).toEqual(["/proj/docs/TASKS.md"])
+    await w.handlers.subscribe!({ sessionID: "s1", path: "docs/TASKS.md" })
+    expect(w.subs.get("s1")!.files).toEqual(["/proj/docs/TASKS.md"])
+    // a config shadow (removed) is lifted by subscribing again
+    w.subs.set("s1", { version: 1, sessionID: "s1", files: [], removed: ["/proj/docs/TASKS.md"], updatedAt: 0 })
+    await w.handlers.subscribe!({ sessionID: "s1", path: "/proj/docs/TASKS.md" })
+    expect(w.subs.get("s1")!.files).toEqual(["/proj/docs/TASKS.md"])
+    expect(w.subs.get("s1")!.removed).toEqual([])
+    await w.handlers.unsubscribe!({ sessionID: "s1", path: "docs/TASKS.md" })
+    expect(w.subs.get("s1")!.files).toEqual([])
+    expect(w.subs.get("s1")!.removed).toEqual(["/proj/docs/TASKS.md"])
+    expect(w.emitted.filter((e) => e.name === "updated").length).toBe(4)
+  })
+
+  test("toggle flips one item, notifies and emits updated", async () => {
+    const w = await setup([
+      { content: "one", status: "pending" },
+      { content: "two", status: "completed" },
+    ])
+    const first = (await w.handlers.toggle!({ sessionID: "s1", index: 0 })) as Record<string, unknown>
+    expect(first.status).toBe("completed")
+    expect(w.todos.get("s1")![0]!.status).toBe("completed")
+    const second = (await w.handlers.toggle!({ sessionID: "s1", index: 1 })) as Record<string, unknown>
+    expect(second.status).toBe("pending")
+    expect(w.calls.filter((call) => call === "changed s1").length).toBe(2)
+    expect(w.emitted.filter((event) => event.name === "updated").length).toBe(2)
+    await expect(w.handlers.toggle!({ sessionID: "s1", index: 9 })).rejects.toThrow(/range/)
+  })
+
+  test("toggleFile rewrites a subscribed file, refuses other paths and notifies", async () => {
+    const dir = "/tmp/opencode"
+    mkdirSync(dir, { recursive: true })
+    const file = `${dir}/rpc-toggle-${process.pid}.md`
+    const other = `${dir}/rpc-toggle-other-${process.pid}.md`
+    writeFileSync(file, "- [ ] one\n- [x] two\n")
+    writeFileSync(other, "- [ ] not subscribed\n")
+    const w = await setup([], dir)
+    await w.handlers.subscribe!({ sessionID: "s1", path: file })
+
+    const toggled = (await w.handlers.toggleFile!({ sessionID: "s1", path: file, line: 1 })) as Record<string, unknown>
+    expect(toggled.state).toBe("completed")
+    expect(readFileSync(file, "utf8")).toContain("- [x] one")
+    await w.handlers.toggleFile!({ sessionID: "s1", path: file, line: 2 })
+    expect(readFileSync(file, "utf8")).toContain("- [ ] two")
+    expect(w.calls.filter((call) => call === "changed s1").length).toBe(2)
+    expect(w.emitted.filter((event) => event.name === "updated").length).toBe(3) // subscribe + 2 toggles
+    await expect(w.handlers.toggleFile!({ sessionID: "s1", path: other, line: 1 })).rejects.toThrow(/not a subscribed/)
+    await expect(w.handlers.toggleFile!({ sessionID: "s1", path: file, line: 9 })).rejects.toThrow(/no checklist item/)
+  })
+
+  test("list reports subscribed files with their existence", async () => {
+    const dir = "/tmp/opencode"
+    mkdirSync(dir, { recursive: true })
+    const file = `${dir}/rpc-todos-${process.pid}.md`
+    writeFileSync(file, "- [ ] one\n- [x] two\n")
+    const w = await setup([], dir)
+    await w.handlers.subscribe!({ sessionID: "s1", path: file })
+    const result = (await w.handlers.list!({ sessionID: "s1" })) as Record<string, unknown>
+    expect(result.files).toEqual([
+      {
+        path: file,
+        exists: true,
+        items: [
+          { content: "one", status: "pending", line: 1 },
+          { content: "two", status: "completed", line: 2 },
+        ],
+      },
+    ])
+  })
+
+  test("config markdownFiles merge into list.files and unsubscribe shadows them", async () => {
+    const options: Options = { ...DEFAULTS, markdownFiles: ["PLAN.md"] }
+    const w = await setup([], "/proj", options)
+    const before = (await w.handlers.list!({ sessionID: "s1" })) as Record<string, unknown>
+    expect(before.files).toEqual([{ path: "/proj/PLAN.md", exists: false, items: [] }])
+    await w.handlers.unsubscribe!({ sessionID: "s1", path: "PLAN.md" })
+    const after = (await w.handlers.list!({ sessionID: "s1" })) as Record<string, unknown>
+    expect(after.files).toEqual([])
+  })
+
+  test("rejects non-markdown paths and invalid input", async () => {
+    const w = await setup()
+    await expect(w.handlers.subscribe!({ sessionID: "s1", path: "notes.txt" })).rejects.toThrow(/markdown/)
+    await expect(w.handlers.list!({})).rejects.toThrow(/sessionID/)
+    await expect(w.handlers.setEnabled!({ sessionID: "s1", enabled: "yes" })).rejects.toThrow(/boolean/)
+  })
+
+  test("handler failures are logged and rethrown", async () => {
+    const w = await setup([{ content: "one", status: "pending" }])
+    const failing = w.store as unknown as { removeTodos: () => Promise<void> }
+    failing.removeTodos = async () => {
+      throw new Error("storage offline")
+    }
+    await expect(w.handlers.clear!({ sessionID: "s1" })).rejects.toThrow(/storage offline/)
+    expect(w.logs.some((line) => line.includes("rpc clear failed"))).toBe(true)
+  })
+
+  test("resolveMarkdownPath resolves against the directory and accepts absolute paths", () => {
+    expect(resolveMarkdownPath("/proj", "TODO.md")).toBe("/proj/TODO.md")
+    expect(resolveMarkdownPath("/proj", "/abs/PLAN.markdown")).toBe("/abs/PLAN.markdown")
+    expect(resolveMarkdownPath("/proj", "UPPER.MD")).toBe("/proj/UPPER.MD")
+    expect(() => resolveMarkdownPath("/proj", "x.txt")).toThrow()
+  })
+})