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

package/src/rpc.ts

@@ -0,0 +1,290 @@
+// todo-supervisor — RPC contract + server registration (PLAN.md §5.6, aspect 11).
+//
+// `TodoRpc` is the shared contract: the server registers it (handlers below)
+// and the TUI imports it (via `opencode-todo-supervisor/rpc`) to build a
+// client and to subscribe to `updated` / `nudged`.
+//
+// Schemas are portable JSON-schema descriptors (the plugin handshake cannot
+// carry effect schemas), so handlers validate their input explicitly.
+import type { Plugin } from "@opencode/plugin"
+import { Rpc } from "@opencode/plugin/rpc"
+import { effectiveFiles, MarkdownCache, resolveMarkdownPath, toggleMarkdownItem } from "./markdown"
+import type { Options } from "./options"
+import type { TodoStore } from "./storage"
+import type { Supervisor } from "./supervisor"
+
+// Kept for consumers/tests that import the resolver from the RPC module.
+export { resolveMarkdownPath } from "./markdown"
+
+const sessionInput = {
+  type: "object",
+  properties: { sessionID: { type: "string" } },
+  required: ["sessionID"],
+  additionalProperties: false,
+} as const
+
+const sessionPathInput = {
+  type: "object",
+  properties: { sessionID: { type: "string" }, path: { type: "string" } },
+  required: ["sessionID", "path"],
+  additionalProperties: false,
+} as const
+
+const objectOutput = { type: "object", additionalProperties: true } as const
+
+export const TodoRpc = Rpc.define({
+  id: "todo",
+  methods: {
+    /** Current list + subscriptions + supervisor snapshot. */
+    list: { input: sessionInput, output: objectOutput },
+    /** Drop the stored list (subscriptions stay). */
+    clear: { input: sessionInput, output: objectOutput },
+    /** Send the nudge now (same dedupe/ownership rules as automatic nudges). */
+    nudge: { input: sessionInput, output: objectOutput },
+    /** Per-session supervision kill switch. */
+    setEnabled: {
+      input: {
+        type: "object",
+        properties: { sessionID: { type: "string" }, enabled: { type: "boolean" } },
+        required: ["sessionID", "enabled"],
+        additionalProperties: false,
+      } as const,
+      output: objectOutput,
+    },
+    /** Flip one session item between completed and pending (panel `x` action, aspect 12). */
+    toggle: {
+      input: {
+        type: "object",
+        properties: { sessionID: { type: "string" }, index: { type: "number" } },
+        required: ["sessionID", "index"],
+        additionalProperties: false,
+      } as const,
+      output: objectOutput,
+    },
+    /** Toggle a checklist item inside a subscribed markdown file (§5.8, panel `x`). */
+    toggleFile: {
+      input: {
+        type: "object",
+        properties: { sessionID: { type: "string" }, path: { type: "string" }, line: { type: "number" } },
+        required: ["sessionID", "path", "line"],
+        additionalProperties: false,
+      } as const,
+      output: objectOutput,
+    },
+    /** Subscribe to a markdown checklist file (§5.8); `.md`/`.markdown` only. */
+    subscribe: { input: sessionPathInput, output: objectOutput },
+    /** Shadow a subscription (config default or stored) — no longer counted. */
+    unsubscribe: { input: sessionPathInput, output: objectOutput },
+  },
+  events: {
+    updated: {
+      schema: {
+        type: "object",
+        properties: { sessionID: { type: "string" } },
+        required: ["sessionID"],
+        additionalProperties: false,
+      } as const,
+    },
+    nudged: {
+      schema: {
+        type: "object",
+        properties: { sessionID: { type: "string" }, reason: { type: "string" } },
+        required: ["sessionID", "reason"],
+        additionalProperties: false,
+      } as const,
+    },
+  },
+})
+
+export interface RpcDeps {
+  store: TodoStore
+  supervisor: Supervisor
+  options: Options
+  /** Per-file parse cache shared with the tools and the supervisor (§5.8). */
+  markdown: MarkdownCache
+  /** Location directory: relative subscription paths resolve against it (§5.8). */
+  directory: string
+  log: (...args: unknown[]) => void
+}
+
+export interface TodoRpcRegistration {
+  dispose(): Promise<void>
+  /** Fire-and-forget event emission (failures are logged, never thrown). */
+  emit(name: "updated" | "nudged", payload: Record<string, unknown>): void
+}
+
+function requireObject(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("invalid input: expected an object")
+  }
+  return value as Record<string, unknown>
+}
+
+function requireString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`invalid input: "${field}" must be a non-empty string`)
+  }
+  return value
+}
+
+function requireBoolean(value: unknown, field: string): boolean {
+  if (typeof value !== "boolean") throw new Error(`invalid input: "${field}" must be a boolean`)
+  return value
+}
+
+function requireNumber(value: unknown, field: string): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    throw new Error(`invalid input: "${field}" must be a non-negative integer`)
+  }
+  return value
+}
+
+export type RpcFileItem = { content: string; status: "pending" | "completed" | "canceled"; line: number }
+export type RpcFileSection = { path: string; exists: boolean; items: RpcFileItem[] }
+
+/** Effective subscription set (§5.8): parsed fresh on every `list` call. */
+async function collectFiles(store: TodoStore, deps: RpcDeps, sessionID: string): Promise<RpcFileSection[]> {
+  const subs = await store.loadSubs(sessionID)
+  return effectiveFiles(deps.options, deps.directory, subs).map((path) => {
+    const parsed = deps.markdown.parse(path)
+    return {
+      path,
+      exists: parsed.exists,
+      items: parsed.items.map((item) => ({
+        content: item.text,
+        status: item.state === "completed" ? "completed" : item.state === "canceled" ? "canceled" : "pending",
+        line: item.line,
+      })),
+    }
+  })
+}
+
+type RpcHandler = (raw: unknown, context?: unknown) => Promise<unknown>
+
+/** Log and rethrow handler failures (the framework maps them to `rpc.internal`). */
+function wrapHandlers<H extends Record<string, RpcHandler>>(handlers: H, log: (...args: unknown[]) => void): H {
+  const wrapped: Record<string, RpcHandler> = {}
+  for (const [name, handler] of Object.entries(handlers)) {
+    wrapped[name] = async (raw, context) => {
+      try {
+        return await handler(raw, context)
+      } catch (err) {
+        log(`rpc ${name} failed: ${String(err)}`)
+        throw err
+      }
+    }
+  }
+  return wrapped as H
+}
+
+export async function registerTodoRpc(ctx: Plugin.Context, deps: RpcDeps): Promise<TodoRpcRegistration> {
+  const { store, supervisor, log } = deps
+  let emitEvent: (name: "updated" | "nudged", payload: Record<string, unknown>) => Promise<void> = async () => {}
+
+  const registration = await ctx.rpc.register(TodoRpc, wrapHandlers({
+    list: async (raw) => {
+      const sessionID = requireString(requireObject(raw).sessionID, "sessionID")
+      await store.refreshTodos(sessionID)
+      return {
+        sessionID,
+        items: store.getTodos(sessionID)?.items ?? [],
+        files: await collectFiles(store, deps, sessionID),
+        supervisor: supervisor.snapshot(sessionID),
+      }
+    },
+    clear: async (raw) => {
+      const sessionID = requireString(requireObject(raw).sessionID, "sessionID")
+      await store.removeTodos(sessionID)
+      supervisor.notifyTodosChanged(sessionID)
+      await emitEvent("updated", { sessionID })
+      log(`rpc clear (${sessionID})`)
+      return { sessionID }
+    },
+    nudge: async (raw) => {
+      const sessionID = requireString(requireObject(raw).sessionID, "sessionID")
+      supervisor.forceNudge(sessionID)
+      log(`rpc nudge (${sessionID})`)
+      return { sessionID }
+    },
+    setEnabled: async (raw) => {
+      const input = requireObject(raw)
+      const sessionID = requireString(input.sessionID, "sessionID")
+      const enabled = requireBoolean(input.enabled, "enabled")
+      supervisor.setEnabled(sessionID, enabled)
+      log(`rpc setEnabled (${sessionID}) enabled=${enabled}`)
+      return { sessionID, enabled }
+    },
+    toggle: async (raw) => {
+      const input = requireObject(raw)
+      const sessionID = requireString(input.sessionID, "sessionID")
+      const index = requireNumber(input.index, "index")
+      const state = await store.refreshTodos(sessionID)
+      const items = state?.items ?? []
+      const item = items[index]
+      if (!item) throw new Error(`invalid input: "index" ${index} is out of range`)
+      const status: "pending" | "completed" = item.status === "completed" ? "pending" : "completed"
+      const next = items.map((entry, i) => (i === index ? { ...entry, status } : entry))
+      await store.setTodos(sessionID, next)
+      supervisor.notifyTodosChanged(sessionID)
+      await emitEvent("updated", { sessionID })
+      log(`rpc toggle (${sessionID}) index=${index} → ${status}`)
+      return { sessionID, index, status }
+    },
+    toggleFile: async (raw) => {
+      const input = requireObject(raw)
+      const sessionID = requireString(input.sessionID, "sessionID")
+      const line = requireNumber(input.line, "line")
+      if (line < 1) throw new Error(`invalid input: "line" must be a positive line number`)
+      const path = resolveMarkdownPath(deps.directory, requireString(input.path, "path"))
+      // Only files that are actually supervised may be edited (§5.8); arbitrary
+      // paths are rejected so the panel cannot write anywhere on disk.
+      const subscribed = effectiveFiles(deps.options, deps.directory, await store.loadSubs(sessionID))
+      if (!subscribed.includes(path)) throw new Error(`invalid input: "${path}" is not a subscribed markdown file`)
+      const state = toggleMarkdownItem(path, line)
+      deps.markdown.invalidate(path)
+      supervisor.notifyTodosChanged(sessionID)
+      await emitEvent("updated", { sessionID })
+      log(`rpc toggleFile (${sessionID}) ${path}:${line} → ${state}`)
+      return { sessionID, path, line, state }
+    },
+    subscribe: async (raw) => {
+      const input = requireObject(raw)
+      const sessionID = requireString(input.sessionID, "sessionID")
+      const path = resolveMarkdownPath(deps.directory, requireString(input.path, "path"))
+      const current = (await store.loadSubs(sessionID)) ?? { files: [], removed: [] }
+      const files = current.files.includes(path) ? current.files : [...current.files, path]
+      const removed = current.removed.filter((entry) => entry !== path)
+      await store.setSubs(sessionID, files, removed)
+      await emitEvent("updated", { sessionID })
+      log(`rpc subscribe (${sessionID}) ${path}`)
+      return { sessionID, path }
+    },
+    unsubscribe: async (raw) => {
+      const input = requireObject(raw)
+      const sessionID = requireString(input.sessionID, "sessionID")
+      const path = resolveMarkdownPath(deps.directory, requireString(input.path, "path"))
+      const current = (await store.loadSubs(sessionID)) ?? { files: [], removed: [] }
+      const files = current.files.filter((entry) => entry !== path)
+      const removed = current.removed.includes(path) ? current.removed : [...current.removed, path]
+      await store.setSubs(sessionID, files, removed)
+      await emitEvent("updated", { sessionID })
+      log(`rpc unsubscribe (${sessionID}) ${path}`)
+      return { sessionID, path }
+    },
+  }, log))
+
+  emitEvent = async (name, payload) => {
+    try {
+      await registration.events.emit(name, payload)
+    } catch (err) {
+      log(`rpc emit ${name} failed: ${String(err)}`)
+    }
+  }
+
+  return {
+    dispose: () => registration.dispose(),
+    emit: (name, payload) => {
+      void emitEvent(name, payload)
+    },
+  }
+}

package/src/storage.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, test } from "bun:test"
+import {
+  hashList,
+  isDone,
+  openItems,
+  TodoStore,
+  type StorageLike,
+  type TodoItem,
+} from "./storage"
+
+export class FakeStorage implements StorageLike {
+  readonly map = new Map<string, unknown>()
+
+  async get(key: string): Promise<unknown> {
+    return this.map.get(key)
+  }
+  async set(key: string, value: unknown): Promise<void> {
+    this.map.set(key, value)
+  }
+  async remove(key: string): Promise<void> {
+    this.map.delete(key)
+  }
+  async scan(options: { prefix: string; after?: string; limit?: number }) {
+    const limit = options.limit ?? 100
+    const keys = [...this.map.keys()].filter((k) => k.startsWith(options.prefix)).sort()
+    const start = options.after ? keys.indexOf(options.after) + 1 : 0
+    const slice = keys.slice(start, start + limit)
+    const last = slice[slice.length - 1]
+    return {
+      entries: slice.map((key) => ({ key, value: this.map.get(key) })),
+      next: start + slice.length < keys.length && last !== undefined ? last : undefined,
+    }
+  }
+}
+
+const items = (n: number): TodoItem[] =>
+  Array.from({ length: n }, (_, i) => ({ content: `task ${i}`, status: "pending" as const }))
+
+describe("TodoStore", () => {
+  test("round-trips items identically in order", async () => {
+    const storage = new FakeStorage()
+    const store = new TodoStore(storage)
+    const written = items(3)
+    await store.setTodos("ses_1", written)
+    expect(store.getTodos("ses_1")?.items).toEqual(written)
+
+    const fresh = new TodoStore(storage)
+    const loaded = await fresh.loadTodos("ses_1")
+    expect(loaded?.items).toEqual(written)
+  })
+
+  test("scanAll paginates through more than one page", async () => {
+    const storage = new FakeStorage()
+    const store = new TodoStore(storage)
+    for (let i = 0; i < 5; i++) {
+      await storage.set(`todos/ses_${i}`, { version: 1, sessionID: `ses_${i}`, items: items(1), updatedAt: 0 })
+    }
+    await storage.set("subs/ses_9", { version: 1, sessionID: "ses_9", files: [], removed: [], updatedAt: 0 })
+
+    const fresh = new TodoStore(storage)
+    const all = await fresh.scanAll({ limit: 2 })
+    expect(all.map((s) => s.sessionID).sort()).toEqual(["ses_0", "ses_1", "ses_2", "ses_3", "ses_4"])
+    expect(fresh.getTodos("ses_4")?.items).toEqual(items(1))
+    expect(fresh.getSubs("ses_9")).toBeUndefined()
+  })
+
+  test("removeTodos deletes the key and the cache entry", async () => {
+    const storage = new FakeStorage()
+    const store = new TodoStore(storage)
+    await store.setTodos("ses_1", items(1))
+    await store.removeTodos("ses_1")
+    expect(storage.map.has("todos/ses_1")).toBe(false)
+    expect(store.getTodos("ses_1")).toBeUndefined()
+  })
+
+  test("garbage in storage is tolerated", async () => {
+    const storage = new FakeStorage()
+    await storage.set("todos/bad", { version: 2, items: "nope" })
+    await storage.set("todos/bad2", { version: 1, sessionID: "bad2", items: [{ content: "ok", status: "weird" }] })
+    const store = new TodoStore(storage)
+    const all = await store.scanAll()
+    expect(all.map((s) => s.sessionID)).toEqual(["bad2"])
+    expect(all[0]?.items).toEqual([])
+  })
+})
+
+describe("helpers", () => {
+  test("openItems / isDone", () => {
+    expect(openItems([{ content: "a", status: "completed" }, { content: "b", status: "pending" }])).toHaveLength(1)
+    expect(isDone([])).toBe(false)
+    expect(isDone([{ content: "a", status: "completed" }, { content: "b", status: "canceled" }])).toBe(true)
+    expect(isDone([{ content: "a", status: "pending" }])).toBe(false)
+  })
+
+  test("hashList is stable and order/content sensitive", () => {
+    const a: TodoItem[] = [{ content: "a", status: "pending", priority: "high" }]
+    const b: TodoItem[] = [{ content: "a", status: "pending", priority: "high" }]
+    expect(hashList(a)).toBe(hashList(b))
+    expect(hashList(a)).not.toBe(hashList([{ content: "a", status: "completed", priority: "high" }]))
+  })
+})

package/src/storage.ts

@@ -0,0 +1,186 @@
+// todo-supervisor — typed wrapper around `ctx.storage` (PLAN.md §5.3).
+//
+// Keys:
+//   todos/<sessionID>  → { version: 1, sessionID, items, updatedAt }
+//   subs/<sessionID>   → { version: 1, sessionID, files, removed, updatedAt }
+//
+// A full in-memory cache keeps the per-request context hook (§5.5)
+// synchronous. Supervision counters are NOT stored — restart resets them.
+export type TodoStatus = "pending" | "in_progress" | "completed" | "canceled"
+export type TodoPriority = "high" | "medium" | "low"
+
+export type TodoItem = {
+  content: string
+  status: TodoStatus
+  priority?: TodoPriority
+}
+
+export type TodoState = {
+  version: 1
+  sessionID: string
+  items: TodoItem[]
+  updatedAt: number
+}
+
+export type SubsState = {
+  version: 1
+  sessionID: string
+  files: string[]
+  removed: string[]
+  updatedAt: number
+}
+
+/** Structural subset of `ctx.storage` (keeps this module testable). */
+export interface StorageLike {
+  get(key: string): Promise<unknown>
+  set(key: string, value: unknown): Promise<void>
+  remove(key: string): Promise<void>
+  scan(options: { prefix: string; after?: string; limit?: number }): Promise<{
+    entries: readonly { key: string; value: unknown }[]
+    next?: string
+  }>
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value)
+}
+
+export function parseTodoState(value: unknown): TodoState | undefined {
+  if (!isRecord(value) || value.version !== 1) return undefined
+  if (typeof value.sessionID !== "string" || !Array.isArray(value.items)) return undefined
+  const items: TodoItem[] = []
+  for (const entry of value.items) {
+    if (!isRecord(entry) || typeof entry.content !== "string") continue
+    const status = entry.status
+    if (status !== "pending" && status !== "in_progress" && status !== "completed" && status !== "canceled") continue
+    const item: TodoItem = { content: entry.content, status }
+    if (entry.priority === "high" || entry.priority === "medium" || entry.priority === "low") {
+      item.priority = entry.priority
+    }
+    items.push(item)
+  }
+  return {
+    version: 1,
+    sessionID: value.sessionID,
+    items,
+    updatedAt: typeof value.updatedAt === "number" ? value.updatedAt : 0,
+  }
+}
+
+export function parseSubsState(value: unknown): SubsState | undefined {
+  if (!isRecord(value) || value.version !== 1) return undefined
+  if (typeof value.sessionID !== "string") return undefined
+  const files = Array.isArray(value.files) ? value.files.filter((f): f is string => typeof f === "string") : []
+  const removed = Array.isArray(value.removed) ? value.removed.filter((f): f is string => typeof f === "string") : []
+  return {
+    version: 1,
+    sessionID: value.sessionID,
+    files,
+    removed,
+    updatedAt: typeof value.updatedAt === "number" ? value.updatedAt : 0,
+  }
+}
+
+const todosKey = (sessionID: string) => `todos/${sessionID}`
+const subsKey = (sessionID: string) => `subs/${sessionID}`
+
+export class TodoStore {
+  private readonly todos = new Map<string, TodoState>()
+  private readonly subs = new Map<string, SubsState>()
+
+  constructor(private readonly storage: StorageLike) {}
+
+  // ---- todos ---------------------------------------------------------------
+
+  /** Cache-only read (kept in sync by every write, load and scan). */
+  getTodos(sessionID: string): TodoState | undefined {
+    return this.todos.get(sessionID)
+  }
+
+  /** Load one list from storage into the cache. */
+  async loadTodos(sessionID: string): Promise<TodoState | undefined> {
+    const parsed = parseTodoState(await this.storage.get(todosKey(sessionID)))
+    if (parsed) this.todos.set(sessionID, parsed)
+    return parsed
+  }
+
+  /** Re-read one list from shared storage; drops the cache entry when the row is gone. */
+  async refreshTodos(sessionID: string): Promise<TodoState | undefined> {
+    const parsed = parseTodoState(await this.storage.get(todosKey(sessionID)))
+    if (parsed) this.todos.set(sessionID, parsed)
+    else this.todos.delete(sessionID)
+    return parsed
+  }
+
+  async setTodos(sessionID: string, items: TodoItem[]): Promise<TodoState> {
+    const state: TodoState = { version: 1, sessionID, items, updatedAt: Date.now() }
+    await this.storage.set(todosKey(sessionID), state)
+    this.todos.set(sessionID, state)
+    return state
+  }
+
+  async removeTodos(sessionID: string): Promise<void> {
+    this.todos.delete(sessionID)
+    await this.storage.remove(todosKey(sessionID))
+  }
+
+  /** All stored lists, page by page; also refreshes the cache. */
+  async scanAll(options: { limit?: number } = {}): Promise<TodoState[]> {
+    const out: TodoState[] = []
+    let after: string | undefined
+    for (;;) {
+      const page = await this.storage.scan({ prefix: "todos/", after, limit: options.limit ?? 100 })
+      for (const entry of page.entries) {
+        const state = parseTodoState(entry.value)
+        if (!state) continue
+        out.push(state)
+        this.todos.set(state.sessionID, state)
+      }
+      if (!page.next) break
+      after = page.next
+    }
+    return out
+  }
+
+  // ---- markdown subscriptions ---------------------------------------------
+
+  getSubs(sessionID: string): SubsState | undefined {
+    return this.subs.get(sessionID)
+  }
+
+  async loadSubs(sessionID: string): Promise<SubsState | undefined> {
+    const parsed = parseSubsState(await this.storage.get(subsKey(sessionID)))
+    if (parsed) this.subs.set(sessionID, parsed)
+    return parsed
+  }
+
+  async setSubs(sessionID: string, files: string[], removed: string[]): Promise<SubsState> {
+    const state: SubsState = { version: 1, sessionID, files, removed, updatedAt: Date.now() }
+    await this.storage.set(subsKey(sessionID), state)
+    this.subs.set(sessionID, state)
+    return state
+  }
+
+  async removeSubs(sessionID: string): Promise<void> {
+    this.subs.delete(sessionID)
+    await this.storage.remove(subsKey(sessionID))
+  }
+}
+
+export function makeStore(storage: StorageLike): TodoStore {
+  return new TodoStore(storage)
+}
+
+// ---- predicates / helpers (§5.3) ------------------------------------------
+
+export function openItems(items: readonly TodoItem[]): TodoItem[] {
+  return items.filter((item) => item.status !== "completed" && item.status !== "canceled")
+}
+
+export function isDone(items: readonly TodoItem[]): boolean {
+  return items.length > 0 && openItems(items).length === 0
+}
+
+export function hashList(items: readonly TodoItem[]): string {
+  return JSON.stringify(items.map((item) => [item.content, item.status, item.priority ?? ""]))
+}

package/src/supervisor.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test"
+import { normalizeEvent, truncate } from "./supervisor"
+
+describe("normalizeEvent", () => {
+  test("accepts the SSE envelope shape", () => {
+    const event = normalizeEvent({ id: "evt_1", type: "session.idle", data: { sessionID: "ses_1" } })
+    expect(event).toEqual({ type: "session.idle", data: { sessionID: "ses_1" } })
+  })
+
+  test("accepts a bare event object", () => {
+    const event = normalizeEvent({ type: "session.idle", sessionID: "ses_1" })
+    expect(event).toEqual({ type: "session.idle", data: { type: "session.idle", sessionID: "ses_1" } })
+  })
+
+  test("falls back to the source when data is not an object", () => {
+    const event = normalizeEvent({ type: "session.updated", data: "nope", sessionID: "ses_2" })
+    expect(event?.type).toBe("session.updated")
+    expect(event?.data.sessionID).toBe("ses_2")
+  })
+
+  test("rejects unusable input", () => {
+    expect(normalizeEvent(undefined)).toBeUndefined()
+    expect(normalizeEvent("session.idle")).toBeUndefined()
+    expect(normalizeEvent({})).toBeUndefined()
+    expect(normalizeEvent({ data: { sessionID: "ses_1" } })).toBeUndefined()
+  })
+})
+
+describe("truncate", () => {
+  test("passes short strings through", () => {
+    expect(truncate("hello", 10)).toBe("hello")
+  })
+
+  test("truncates long strings with a marker", () => {
+    expect(truncate("x".repeat(20), 5)).toBe("xxxxx…(15 more)")
+  })
+})