@brimveyn/aimux-plugin 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux-plugin",
-  "version": "0.1.3",
+  "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

@@ -43,13 +43,19 @@ export {
 export type {
   PluginActionsApi,
   PluginBarWidget,
+  PluginCommitMessage,
+  PluginCommitMessageRequest,
   PluginComponent,
+  PluginGitApi,
+  PluginGitFile,
+  PluginGitStatus,
   PluginKit,
   PluginModal,
   PluginModalsApi,
   PluginNode,
   PluginPane,
   PluginPanesApi,
+  PluginScreen,
   PluginSettingsApi,
   PluginSettingValue,
   PluginStateApi,
@@ -68,6 +74,7 @@ export type {
   PluginView,
   PluginViewsApi,
   PluginWidgetsApi,
+  PluginWidgetSize,
 } from './ui'
 export type {
   DaemonPluginContext,

package/src/test-ui.ts

@@ -2,6 +2,9 @@ import type { EffectStack } from './effects'
 import type { Disposer } from './types'
 import type {
   PluginActionsApi,
+  PluginCommitMessage,
+  PluginCommitMessageRequest,
+  PluginGitStatus,
   PluginSettingValue,
   PluginStoreApi,
   PluginThemeSnapshot,
@@ -36,6 +39,8 @@ export interface TestUiRegistrations {
   statsPages: string[]
   themes: string[]
   settingsSections: number
+  /** Whether the plugin claimed the commit-message slot. */
+  commitMessageProvider: boolean
   actions: string[]
   effects: string[]
 }
@@ -55,6 +60,16 @@ export interface TestUiSurface {
   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 = {
@@ -66,12 +81,25 @@ const EMPTY_STATE: PluginUiState = {
 
 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: [],
@@ -92,6 +120,13 @@ export function createTestUiSurface(effects: EffectStack): TestUiSurface {
   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 {
@@ -114,6 +149,19 @@ export function createTestUiSurface(effects: EffectStack): TestUiSurface {
   }
 
   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,
@@ -126,6 +174,7 @@ export function createTestUiSurface(effects: EffectStack): TestUiSurface {
       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}`),
@@ -207,8 +256,15 @@ export function createTestUiSurface(effects: EffectStack): TestUiSurface {
 
   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)

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