@brimveyn/aimux-plugin 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux-plugin",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Plugin authoring API for aimux — context, effects, events and RPC for in-process plugins.",
   "keywords": [
     "aimux",
@@ -28,7 +28,8 @@
   ],
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./testing": "./src/testing.ts"
   },
   "publishConfig": {
     "access": "public"
@@ -37,6 +38,16 @@
     "@types/react": "^19.2.14"
   },
   "peerDependencies": {
+    "@opentui/core": ">=0.1.90",
+    "@opentui/react": ">=0.1.90",
     "react": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/core": {
+      "optional": true
+    },
+    "@opentui/react": {
+      "optional": true
+    }
   }
 }

package/src/daemon-api.ts

@@ -22,6 +22,16 @@ export interface PluginTabView {
   command: string
   workspaceId?: string
   workerName?: string
+  /**
+   * True while the tab still carries the title it was born with: created
+   * without one, on an assistant that supports being named, and renamed by
+   * nobody since — not the user, not aimux, not a plugin.
+   *
+   * A plugin that names tabs reads this before naming one, which is how it
+   * avoids naming the same tab twice or writing over a title the user chose.
+   * `rename` clears it, whoever calls it.
+   */
+  unnamed: boolean
 }
 
 export interface PluginSpawnTabInput {

package/src/index.ts

@@ -32,6 +32,7 @@ export {
   type PluginKeymapContribution,
   type PluginManifest,
 } from './manifest'
+export { createTestUiSurface, type TestUiRegistrations, type TestUiSurface } from './test-ui'
 export {
   createTestContext,
   type TestContextHandle,
@@ -42,13 +43,19 @@ export {
 export type {
   PluginActionsApi,
   PluginBarWidget,
+  PluginCommitMessage,
+  PluginCommitMessageRequest,
   PluginComponent,
+  PluginGitApi,
+  PluginGitFile,
+  PluginGitStatus,
   PluginKit,
   PluginModal,
   PluginModalsApi,
   PluginNode,
   PluginPane,
   PluginPanesApi,
+  PluginScreen,
   PluginSettingsApi,
   PluginSettingValue,
   PluginStateApi,
@@ -67,6 +74,7 @@ export type {
   PluginView,
   PluginViewsApi,
   PluginWidgetsApi,
+  PluginWidgetSize,
 } from './ui'
 export type {
   DaemonPluginContext,

package/src/test-context.ts

@@ -9,6 +9,7 @@ import type {
 import { EffectStack } from './effects'
 import { PluginEventBus } from './event-bus'
 import { PLUGIN_API_VERSION, type PluginHost, type PluginManifest } from './manifest'
+import { createTestUiSurface, type TestUiSurface } from './test-ui'
 
 export interface TestLogEntry {
   level: 'debug' | 'info' | 'warn' | 'error'
@@ -73,6 +74,13 @@ export interface TestContextHandle {
   effectCount: () => number
   /** Unwind, exactly as an unload would. Resolves with any disposer errors. */
   dispose: () => Promise<unknown[]>
+  /**
+   * The recording UI half, when `host` is `'ui'` and no `extend` replaced it:
+   * what the plugin registered, the toasts it raised, and the levers that drive
+   * `ctx.ui.state`, `ctx.ui.settings` and `ctx.ui.themes`. Absent for a daemon
+   * plugin, which has no `ctx.ui` to record.
+   */
+  ui?: TestUiSurface
 }
 
 /**
@@ -191,9 +199,28 @@ export function createTestContext(options: TestContextOptions = {}): TestContext
     waterfall: async <T>(event: string, value: T) => bus.waterfall(event, value),
   }
 
+  /**
+   * A UI plugin's first line is `ctx.ui.something.register(...)`, so a `ui`
+   * context without `ctx.ui` cannot run one at all. `extend` still wins: the
+   * real hosts and `plugin doctor` pass their own services, and this stub is
+   * what an author outside aimux gets instead.
+   */
+  const surface = host === 'ui' ? createTestUiSurface(effects) : undefined
+  if (surface) {
+    const extended = ctx as PluginContext & {
+      ui: unknown
+      actions: unknown
+      store: unknown
+    }
+    extended.ui = surface.ui
+    extended.actions = surface.actions
+    extended.store = surface.store
+  }
+
   options.extend?.(ctx)
 
   return {
+    ...(surface === undefined ? {} : { ui: surface }),
     apply: async (definition) => {
       await (definition as PluginDefinition).apply(ctx)
     },

package/src/test-ui.ts

@@ -0,0 +1,284 @@
+import type { EffectStack } from './effects'
+import type { Disposer } from './types'
+import type {
+  PluginActionsApi,
+  PluginCommitMessage,
+  PluginCommitMessageRequest,
+  PluginGitStatus,
+  PluginSettingValue,
+  PluginStoreApi,
+  PluginThemeSnapshot,
+  PluginUiApi,
+  PluginUiState,
+} from './ui'
+
+/**
+ * The UI half of a plugin, with no aimux drawing anything.
+ *
+ * `createTestContext` gives a daemon plugin everything it needs — the real bus,
+ * the real effect stack, recorded RPC — but a UI plugin's first line is
+ * `ctx.ui.widgets.register(...)`, and `ctx.ui` simply was not there. So the
+ * test the scaffold generates, against the half the scaffold generates, threw
+ * on the first statement: the author's first run of `bun test` was a red they
+ * had not written. Inside this repo it was invisible, because aimux's own tests
+ * pass `extend` with the real services.
+ *
+ * Everything here records rather than draws, and every registration goes on the
+ * same effect stack the rest of the context uses — so `effectCount()` counts
+ * them and `dispose()` unwinds them, which is the property a plugin test is
+ * really there to check.
+ */
+
+/** What the plugin registered, by surface. Mirrors what `plugin doctor` reports. */
+export interface TestUiRegistrations {
+  widgets: string[]
+  views: string[]
+  modals: string[]
+  panes: string[]
+  statusBar: string[]
+  statsPages: string[]
+  themes: string[]
+  settingsSections: number
+  /** Whether the plugin claimed the commit-message slot. */
+  commitMessageProvider: boolean
+  actions: string[]
+  effects: string[]
+}
+
+export interface TestUiSurface {
+  ui: PluginUiApi
+  actions: PluginActionsApi
+  store: PluginStoreApi
+  registrations: TestUiRegistrations
+  /** Everything `ctx.ui.toast` was asked to show, newest last. */
+  toasts: { level: 'info' | 'success' | 'error'; message: string }[]
+  /** Panes and views the plugin asked to open or close, in order. */
+  opened: string[]
+  /** Drives `ctx.ui.state`: set it, and subscribers hear about it. */
+  setState: (next: Partial<PluginUiState>) => void
+  /** Drives `ctx.ui.settings.watch` and what `get` answers. */
+  setSetting: (id: string, value: PluginSettingValue) => void
+  /** Drives `ctx.ui.themes.onChange` and what `current()` answers. */
+  setTheme: (snapshot: PluginThemeSnapshot) => void
+  /** Drives `ctx.ui.git.status`. */
+  setGitStatus: (status: PluginGitStatus) => void
+  /**
+   * Asks the provider the plugin registered, as the commit flow would. Throws
+   * when it registered none, because a test that silently asserts nothing is
+   * the failure this whole harness exists to avoid.
+   */
+  askForCommitMessage: (
+    request?: Partial<PluginCommitMessageRequest>
+  ) => Promise<PluginCommitMessage | null>
+}
+
+const EMPTY_STATE: PluginUiState = {
+  activeTab: null,
+  activeTabId: null,
+  projectId: null,
+  tabs: [],
+}
+
+const DEFAULT_THEME: PluginThemeSnapshot = { colors: {}, mode: 'dark' }
+
+const EMPTY_GIT: PluginGitStatus = { ahead: 0, behind: 0, branch: null, files: [] }
+
+const EMPTY_REQUEST: PluginCommitMessageRequest = {
+  assistant: 'claude',
+  branch: 'main',
+  diff: '',
+  files: [],
+  projectId: 'p1',
+  recentCommits: '',
+  repoRoot: '/tmp/repo',
+}
+
+/** A component that renders nothing: a test asserts on registrations, not pixels. */
+const nothing = (): null => null
+
+export function createTestUiSurface(effects: EffectStack): TestUiSurface {
+  const registrations: TestUiRegistrations = {
+    actions: [],
+    commitMessageProvider: false,
+    effects: [],
+    modals: [],
+    panes: [],
+    settingsSections: 0,
+    statsPages: [],
+    statusBar: [],
+    themes: [],
+    views: [],
+    widgets: [],
+  }
+  const toasts: TestUiSurface['toasts'] = []
+  const opened: string[] = []
+
+  let state: PluginUiState = EMPTY_STATE
+  const stateListeners = new Set<(next: PluginUiState) => void>()
+  const settings = new Map<string, PluginSettingValue>()
+  const settingListeners = new Map<string, Set<(value: PluginSettingValue) => void>>()
+  let theme: PluginThemeSnapshot = DEFAULT_THEME
+  const themeListeners = new Set<(snapshot: PluginThemeSnapshot) => void>()
+  let slice: unknown
+  let git: PluginGitStatus = EMPTY_GIT
+  let commitProvider:
+    | ((
+        request: PluginCommitMessageRequest,
+        signal: AbortSignal
+      ) => Promise<PluginCommitMessage | null> | PluginCommitMessage | null)
+    | null = null
+
+  /** Records a registration and hands back a disposer that unrecords it. */
+  function record(into: string[], id: string): Disposer {
+    into.push(id)
+    const dispose = (): void => {
+      const at = into.indexOf(id)
+      if (at !== -1) into.splice(at, 1)
+    }
+    effects.add(dispose)
+    return dispose
+  }
+
+  function own<T>(set: Set<T>, listener: T): Disposer {
+    set.add(listener)
+    const dispose = (): void => {
+      set.delete(listener)
+    }
+    effects.add(dispose)
+    return dispose
+  }
+
+  const ui: PluginUiApi = {
+    git: {
+      provideCommitMessage: (provider) => {
+        commitProvider = provider
+        registrations.commitMessageProvider = true
+        const dispose = (): void => {
+          if (commitProvider === provider) commitProvider = null
+          registrations.commitMessageProvider = false
+        }
+        effects.add(dispose)
+        return dispose
+      },
+      status: () => git,
+    },
+    kit: {
+      KeyHint: nothing,
+      List: nothing,
+      Panel: nothing,
+      Row: nothing,
+      useTheme: () => theme.colors,
+    },
+    modals: {
+      close: () => opened.push('modal:close'),
+      open: (id) => opened.push(`modal:${id}`),
+      register: (modal) => record(registrations.modals, modal.id),
+    },
+    navigate: (screen) => opened.push(`screen:${screen}`),
+    panes: {
+      close: (id) => opened.push(`pane:close:${id}`),
+      open: (id) => opened.push(`pane:${id}`),
+      register: (pane) => record(registrations.panes, pane.id),
+    },
+    settings: {
+      get: (id) => settings.get(id),
+      registerSection: () => {
+        registrations.settingsSections += 1
+        const dispose = (): void => {
+          registrations.settingsSections -= 1
+        }
+        effects.add(dispose)
+        return dispose
+      },
+      watch: (id, listener) => {
+        const set = settingListeners.get(id) ?? new Set()
+        settingListeners.set(id, set)
+        return own(set, listener)
+      },
+    },
+    state: {
+      get: () => state,
+      subscribe: (listener) => {
+        // Fires once immediately, exactly as the real one does.
+        listener(state)
+        return own(stateListeners, listener)
+      },
+      use: (select) => select(state),
+    },
+    stats: {
+      registerPage: (page) => record(registrations.statsPages, page.id),
+    },
+    statusBar: {
+      register: (segment) => record(registrations.statusBar, segment.id),
+    },
+    themes: {
+      current: () => theme,
+      onChange: (listener) => own(themeListeners, listener),
+      register: (id) => record(registrations.themes, id),
+    },
+    toast: {
+      error: (message) => toasts.push({ level: 'error', message }),
+      info: (message) => toasts.push({ level: 'info', message }),
+      success: (message) => toasts.push({ level: 'success', message }),
+    },
+    views: {
+      close: () => opened.push('view:close'),
+      open: (id) => opened.push(`view:${id}`),
+      register: (view) => record(registrations.views, view.id),
+    },
+    widgets: {
+      register: (widget) => record(registrations.widgets, widget.id),
+    },
+  }
+
+  const actions: PluginActionsApi = {
+    effect: (effectId) => record(registrations.effects, effectId),
+    register: (verb) => record(registrations.actions, verb),
+  }
+
+  const store: PluginStoreApi = {
+    dispatch: () => {
+      /* a slice reducer is the plugin's; a bare context has none to run */
+    },
+    get: () => slice,
+    reducer: () => {
+      const dispose = (): void => {
+        /* nothing was installed, so nothing comes off */
+      }
+      effects.add(dispose)
+      return dispose
+    },
+    set: (next) => {
+      slice = next
+    },
+    use: () => slice,
+  }
+
+  return {
+    actions,
+    askForCommitMessage: async (request) => {
+      if (commitProvider === null) throw new Error('the plugin registered no commit provider')
+      return commitProvider({ ...EMPTY_REQUEST, ...request }, new AbortController().signal)
+    },
+    opened,
+    registrations,
+    setGitStatus: (status) => {
+      git = status
+    },
+    setSetting: (id, value) => {
+      settings.set(id, value)
+      for (const listener of settingListeners.get(id) ?? []) listener(value)
+    },
+    setState: (next) => {
+      state = { ...state, ...next }
+      for (const listener of stateListeners) listener(state)
+    },
+    setTheme: (snapshot) => {
+      theme = snapshot
+      for (const listener of themeListeners) listener(snapshot)
+    },
+    store,
+    toasts,
+    ui,
+  }
+}

package/src/testing.ts

@@ -0,0 +1,99 @@
+import { createTestRenderer } from '@opentui/core/testing'
+import { createRoot } from '@opentui/react'
+
+import type { PluginNode } from './ui'
+
+/**
+ * Does it draw?
+ *
+ * `createTestContext` answers what a plugin *registers* — the widget exists,
+ * the action is bound, an unload leaves nothing behind. It says nothing about
+ * what any of it looks like, and a widget whose renderer throws on an empty
+ * data set registers exactly as cleanly as one that works.
+ *
+ * aimux has a test renderer; a plugin author outside this repo did not. This is
+ * that renderer, with the two lines of setup already done, in a separate entry
+ * point so the extra dependencies stay out of a plugin's runtime:
+ *
+ * ```ts
+ * import { renderPluginNode } from '@brimveyn/aimux-plugin/testing'
+ *
+ * const { frame } = await renderPluginNode(<MyWidget cols={30} rows={8} />)
+ * expect(frame).toContain('CPU')
+ * ```
+ *
+ * `@opentui/core` and `@opentui/react` are peers rather than dependencies: the
+ * host already ships them, and a second copy in a plugin's tree is the module
+ * duplication the plugin loader spends real effort avoiding at runtime.
+ */
+
+export interface RenderPluginOptions {
+  /** Terminal size to render into. Defaults to a bar-sized 40×12. */
+  cols?: number
+  rows?: number
+  /**
+   * How long to keep rendering while `until` is false. A widget that fetches on
+   * mount needs a few frames before it has anything to draw.
+   */
+  timeoutMs?: number
+  /** Stop as soon as this is true of the current frame. Default: first frame. */
+  until?: (frame: string) => boolean
+}
+
+export interface RenderedPlugin {
+  /** The drawn frame, as text. */
+  frame: string
+  /** Renders again and returns the new frame — for asserting on a change. */
+  next: () => Promise<string>
+  /** Tears the renderer down. Call it, or the process keeps a root mounted. */
+  dispose: () => void
+}
+
+const DEFAULT_COLS = 40
+const DEFAULT_ROWS = 12
+const DEFAULT_TIMEOUT_MS = 2_000
+/** One macrotask, which is what React needs to commit the tree. */
+const COMMIT_TICK_MS = 10
+
+export async function renderPluginNode(
+  node: PluginNode,
+  options: RenderPluginOptions = {}
+): Promise<RenderedPlugin> {
+  const cols = options.cols ?? DEFAULT_COLS
+  const rows = options.rows ?? DEFAULT_ROWS
+  const { captureCharFrame, renderer, renderOnce } = await createTestRenderer({
+    height: rows,
+    width: cols,
+  })
+  const root = createRoot(renderer)
+  root.render(node)
+
+  const draw = async (): Promise<string> => {
+    await renderOnce()
+    return captureCharFrame()
+  }
+
+  // React commits on a macrotask, not on the render tick: capturing straight
+  // after `root.render` gives a blank frame every time, which would make the
+  // simplest possible assertion fail for a reason that has nothing to do with
+  // the widget under test.
+  await draw()
+  await new Promise<void>((resolve) => setTimeout(resolve, COMMIT_TICK_MS))
+  let frame = await draw()
+  const until = options.until
+  if (until !== undefined) {
+    const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS)
+    while (!until(frame) && Date.now() < deadline) {
+      await new Promise<void>((resolve) => setTimeout(resolve, 10))
+      frame = await draw()
+    }
+  }
+
+  return {
+    dispose: () => {
+      root.unmount()
+    },
+    frame,
+    next: draw,
+  }
+}

package/src/ui.ts

@@ -36,11 +36,23 @@ export interface PluginToastApi {
   error: (message: string) => void
 }
 
+/** The room a bar widget has been given, in cells. */
+export interface PluginWidgetSize {
+  cols: number
+  rows: number
+}
+
 export interface PluginBarWidget {
   /** Unqualified; the host prefixes the plugin id. */
   id: string
   label: string
-  render: (contentWidth: number) => PluginNode
+  /**
+   * `size` is the second argument rather than a replacement for the first: the
+   * width already shipped as a number under `apiVersion: 1`, and swapping it
+   * would break every published plugin to save one parameter. `size.cols` is
+   * the same value.
+   */
+  render: (contentWidth: number, size: PluginWidgetSize) => PluginNode
 }
 
 export interface PluginView {
@@ -269,7 +281,84 @@ export interface PluginKit {
   KeyHint: PluginComponent<{ hints: readonly { keys: string; label: string }[] }>
 }
 
+/** One changed file, as the git panel sees it. */
+export interface PluginGitFile {
+  path: string
+  /** Porcelain-ish status: `modified`, `new`, `deleted`, `renamed`, … */
+  status: string
+  /** Which half of the panel it sits in — staged or not. */
+  section: string
+  added: number | null
+  removed: number | null
+}
+
+/**
+ * The working tree as the panel last saw it. A snapshot of aimux's poll, not a
+ * fresh `git status`: it is what the user is looking at, which is the point,
+ * and it is empty until a project with a path is open.
+ */
+export interface PluginGitStatus {
+  branch: string | null
+  ahead: number
+  behind: number
+  files: PluginGitFile[]
+}
+
+/** Everything aimux gathered before asking for a commit message. */
+export interface PluginCommitMessageRequest {
+  projectId: string
+  repoRoot: string
+  branch: string
+  /**
+   * The assistant in the tab the commit is being written for — `claude`,
+   * `codex`, … A provider that calls a model headlessly needs to know which
+   * one the user is already working with.
+   */
+  assistant: string
+  /** Staged diff when anything is staged, the working-tree diff otherwise. */
+  diff: string
+  /** `git log --oneline`, for house style rather than for content. */
+  recentCommits: string
+  files: PluginGitFile[]
+  /** The tail of what the agent in the tab was doing, when there is one. */
+  sessionTail?: string
+}
+
+export interface PluginCommitMessage {
+  title: string
+  body?: string
+}
+
+export interface PluginGitApi {
+  /** The panel's last refresh. */
+  status: () => PluginGitStatus
+  /**
+   * Answers "what should this commit say", replacing the headless model call
+   * aimux would otherwise make. Return `null` to decline this one — aimux falls
+   * back to its own suggestion rather than leaving the user with nothing.
+   *
+   * One plugin at a time: the second to ask is refused, and told so in its log,
+   * because a message that depends on load order is worse than no message.
+   */
+  provideCommitMessage: (
+    provider: (
+      request: PluginCommitMessageRequest,
+      signal: AbortSignal
+    ) => Promise<PluginCommitMessage | null> | PluginCommitMessage | null
+  ) => Disposer
+}
+
+/** The screens a plugin may send the user to. */
+export type PluginScreen = 'git' | 'stats' | 'settings' | 'terminal'
+
 export interface PluginUiApi {
+  /**
+   * Opens one of aimux's own screens, or `terminal` to leave the one you are
+   * on. Deliberately four names and not an id space: exposing modal or view ids
+   * would make them API, and they are not.
+   */
+  navigate: (screen: PluginScreen) => void
+  git: PluginGitApi
   widgets: PluginWidgetsApi
   views: PluginViewsApi
   modals: PluginModalsApi