@brimveyn/aimux-plugin 0.1.2

package/src/manifest.ts

@@ -0,0 +1,109 @@
+// The manifest — `aimux-plugin.json` — is everything the host must know
+// *before* it runs a line of plugin code: which halves exist (so it knows
+// which process to reload), which API version the code was written against,
+// what configuration it takes (so the settings screen can be generated), and
+// which subprocess commands it contributes.
+//
+// It is therefore parsed and validated on its own, never by importing the
+// plugin. `validateManifest` in the host reports the offending field by name.
+
+/** API generation the plugin was written against. Bumped only on a break. */
+export const PLUGIN_API_VERSION = 1
+
+/** Which host process a plugin half runs in. The terminal manager loads none. */
+export type PluginHost = 'ui' | 'daemon'
+
+export type PluginConfigFieldType = 'string' | 'number' | 'boolean'
+
+export interface PluginConfigField {
+  type: PluginConfigFieldType
+  /** Shown as the settings-row label; defaults to the field key. */
+  label?: string
+  description?: string
+  /** Applied when neither the registry nor `aimux.config.ts` provides a value. */
+  default?: string | number | boolean
+  /** Required fields make the plugin fail to load rather than misbehave. */
+  required?: boolean
+  /**
+   * Secrets are never echoed: not in `aimux plugin list`, not in the settings
+   * screen, not in the plugin log. Storage is still plaintext JSON — this is
+   * shoulder-surfing hygiene, not encryption.
+   */
+  secret?: boolean
+}
+
+/**
+ * A subprocess contribution, herdr-style. Interpreted by the built-in
+ * `aimux.exec` plugin (phase 3); parsed and carried here from day one so a
+ * manifest written against the documented schema does not have to change.
+ */
+export interface PluginCommandSpec {
+  id: string
+  title?: string
+  /** argv, not a shell string — no quoting rules to get wrong. */
+  command: string[]
+  /** Where the command may be invoked from. */
+  contexts?: string[]
+}
+
+/**
+ * Where a plugin's bar widget goes when nothing has placed it yet.
+ *
+ * A proposal, not a claim: the host places it once, marks the placement as the
+ * plugin's, and never re-places it — so a user who moves it, hides it, or
+ * throws it out has the last word, and an unload withdraws only what it put
+ * there and the user left alone.
+ */
+export interface PluginBarContribution {
+  /** Unqualified widget id — the same one `ctx.ui.widgets.register` takes. */
+  widget: string
+  /** Default `left`. */
+  side?: 'left' | 'right'
+  /** Default `end`. */
+  position?: 'start' | 'end'
+  /** Share of the bar, relative to its neighbours. Default 50. */
+  grow?: number
+}
+
+/**
+ * A keybinding a plugin asks for. Refused rather than applied when the key is
+ * already bound in `aimux.config.ts`: the file the user writes by hand outranks
+ * every plugin, here as everywhere else.
+ */
+export interface PluginKeymapContribution {
+  /** Mode id, e.g. `navigation`, or the plugin's own pane mode. */
+  mode: string
+  /** Key notation, `<leader>` included. */
+  key: string
+  /** Unqualified action verb — the host prefixes it with the plugin id. */
+  action: string
+}
+
+export interface PluginContributions {
+  bars?: PluginBarContribution[]
+  keymaps?: PluginKeymapContribution[]
+}
+
+export interface PluginManifest {
+  /** Reverse-DNS-ish, `<vendor>.<name>`; the namespace for every registration. */
+  id: string
+  /** Human-facing name. Defaults to `id` when absent. */
+  name?: string
+  version: string
+  description?: string
+  /** Refuses to load on an older aimux. Semver, compared numerically. */
+  minAimuxVersion?: string
+  apiVersion: number
+  /** Entry files per host, relative to the plugin root. Both are optional. */
+  entries?: Partial<Record<PluginHost, string>>
+  /** argv lists run once at install/link time (typically `bun install`). */
+  build?: string[][]
+  config?: Record<string, PluginConfigField>
+  commands?: PluginCommandSpec[]
+  /**
+   * What the plugin asks the interface for: a place for its widget, a key for
+   * its action. Applied by the host when the UI half loads, withdrawn when it
+   * unloads, and outranked by anything the user has decided.
+   */
+  contributes?: PluginContributions
+}

package/src/test-context.ts

@@ -0,0 +1,215 @@
+import type {
+  Disposer,
+  PluginContext,
+  PluginDefinition,
+  PluginEventListener,
+  PluginPaths,
+} from './types'
+
+import { EffectStack } from './effects'
+import { PluginEventBus } from './event-bus'
+import { PLUGIN_API_VERSION, type PluginHost, type PluginManifest } from './manifest'
+
+export interface TestLogEntry {
+  level: 'debug' | 'info' | 'warn' | 'error'
+  message: string
+  data?: Record<string, unknown>
+}
+
+export interface TestRpcCall {
+  verb: string
+  payload: unknown
+}
+
+export interface TestContextOptions {
+  id?: string
+  host?: PluginHost
+  config?: Record<string, unknown>
+  manifest?: Partial<PluginManifest>
+  paths?: Partial<PluginPaths>
+  /** Services the plugin can read through `ctx.service(...)`. */
+  services?: Record<string, unknown>
+  /**
+   * Stands in for the other half. Return a value (or a promise) to resolve
+   * `ctx.rpc.call`; leave it out and every call rejects the way an unhandled
+   * verb does in production.
+   */
+  onCall?: (verb: string, payload: unknown) => unknown
+  /**
+   * Attaches host services to the context, the way the real hosts do through
+   * the kernel's `extendContext`. Without it a plugin that touches `ctx.ui` or
+   * `ctx.tabs` cannot be applied here at all — which is what made
+   * `aimux plugin doctor` unable to check the plugins that need checking most.
+   *
+   * A test usually wants recording stubs; `doctor` supplies exactly that.
+   */
+  extend?: (ctx: PluginContext) => void
+}
+
+export interface TestContextHandle {
+  ctx: PluginContext
+  bus: PluginEventBus
+  /** Every `ctx.log.*` line, in order. */
+  logs: TestLogEntry[]
+  /** Every `ctx.rpc.call` the plugin made. */
+  calls: TestRpcCall[]
+  /** Every `ctx.rpc.broadcast` the plugin sent. */
+  broadcasts: TestRpcCall[]
+  /** Services the plugin published via `ctx.provide`. */
+  provided: Map<string, unknown>
+  /**
+   * Run a definition's `apply` against this context. Generic so an inline
+   * `{ apply(ctx) { … } }` infers the base context and a typed
+   * `PluginDefinition<UiPluginContext>` is accepted as written.
+   */
+  apply: <Ctx extends PluginContext = PluginContext>(
+    definition: PluginDefinition<Ctx>
+  ) => Promise<void>
+  /** Call a verb the plugin registered with `ctx.rpc.handle`. */
+  invoke: <T = unknown>(verb: string, payload?: unknown) => Promise<T>
+  /** Verbs the plugin currently handles. */
+  handledVerbs: () => string[]
+  /** How many disposers the plugin has registered and not yet released. */
+  effectCount: () => number
+  /** Unwind, exactly as an unload would. Resolves with any disposer errors. */
+  dispose: () => Promise<unknown[]>
+}
+
+/**
+ * A standalone plugin context for tests, with no aimux process behind it.
+ * The event bus and effect stack are the real implementations, so `bail`,
+ * `waterfall` and disposal ordering behave as they do at runtime; only the
+ * process-crossing parts (RPC, filesystem paths) are stubs the test drives.
+ *
+ * ```ts
+ * const t = createTestContext({ config: { botToken: 'x' } })
+ * await t.apply(plugin)
+ * t.bus.emit('tab:turnComplete', { tabId: 't1' })
+ * expect(t.calls).toHaveLength(1)
+ * await t.dispose()
+ * expect(t.effectCount()).toBe(0)
+ * ```
+ */
+export function createTestContext(options: TestContextOptions = {}): TestContextHandle {
+  const id = options.id ?? 'test.plugin'
+  const host: PluginHost = options.host ?? 'daemon'
+  const logs: TestLogEntry[] = []
+  const calls: TestRpcCall[] = []
+  const broadcasts: TestRpcCall[] = []
+  const provided = new Map<string, unknown>()
+  const handlers = new Map<string, (payload: unknown) => unknown>()
+  const services = new Map<string, unknown>(Object.entries(options.services ?? {}))
+
+  const bus = new PluginEventBus({
+    onError: (error, context) => {
+      logs.push({
+        data: { error: String(error), event: context.event },
+        level: 'error',
+        message: 'listener failed',
+      })
+    },
+  })
+  const effects = new EffectStack()
+
+  const record =
+    (level: TestLogEntry['level']) =>
+    (message: string, data?: Record<string, unknown>): void => {
+      logs.push(data === undefined ? { level, message } : { data, level, message })
+    }
+
+  const manifest: PluginManifest = {
+    apiVersion: PLUGIN_API_VERSION,
+    id,
+    name: id,
+    version: '0.0.0',
+    ...options.manifest,
+  }
+
+  const paths: PluginPaths = {
+    config: `/tmp/aimux-test/${id}/config`,
+    log: `/tmp/aimux-test/${id}/state/plugin.log`,
+    root: `/tmp/aimux-test/${id}`,
+    state: `/tmp/aimux-test/${id}/state`,
+    ...options.paths,
+  }
+
+  const ctx: PluginContext = {
+    bail: async (event, payload) => bus.bail(event, payload),
+    config: options.config ?? {},
+    effect: (setup) => {
+      void effects.run(setup)
+    },
+    emit: (event, payload) => {
+      bus.emit(event, payload)
+    },
+    host,
+    id,
+    log: {
+      debug: record('debug'),
+      error: record('error'),
+      info: record('info'),
+      warn: record('warn'),
+    },
+    manifest,
+    on: <T = unknown>(event: string, listener: PluginEventListener<T>): Disposer => {
+      const off = bus.on(event, listener, id)
+      effects.add(off)
+      return off
+    },
+    parallel: async (event, payload) => bus.parallel(event, payload),
+    paths,
+    provide: (name, value) => {
+      provided.set(name, value)
+      services.set(name, value)
+      effects.add(() => {
+        provided.delete(name)
+        services.delete(name)
+      })
+    },
+    rpc: {
+      broadcast: (verb, payload) => {
+        broadcasts.push({ payload, verb })
+      },
+      call: async <T = unknown>(verb: string, payload?: unknown): Promise<T> => {
+        calls.push({ payload, verb })
+        if (!options.onCall) {
+          throw new Error(`no handler for plugin rpc verb: ${id}.${verb}`)
+        }
+        return (await options.onCall(verb, payload)) as T
+      },
+      handle: (verb, handler) => {
+        handlers.set(verb, handler)
+        const off = (): void => {
+          if (handlers.get(verb) === handler) handlers.delete(verb)
+        }
+        effects.add(off)
+        return off
+      },
+    },
+    serial: async (event, payload) => bus.serial(event, payload),
+    service: <T = unknown>(name: string): T | undefined => services.get(name) as T | undefined,
+    waterfall: async <T>(event: string, value: T) => bus.waterfall(event, value),
+  }
+
+  options.extend?.(ctx)
+
+  return {
+    apply: async (definition) => {
+      await (definition as PluginDefinition).apply(ctx)
+    },
+    broadcasts,
+    bus,
+    calls,
+    ctx,
+    dispose: async () => effects.dispose(),
+    effectCount: () => effects.size,
+    handledVerbs: () => [...handlers.keys()],
+    invoke: async <T = unknown>(verb: string, payload?: unknown): Promise<T> => {
+      const handler = handlers.get(verb)
+      if (!handler) throw new Error(`no handler for plugin rpc verb: ${id}.${verb}`)
+      return (await handler(payload)) as T
+    },
+    logs,
+    provided,
+  }
+}

package/src/types.ts

@@ -0,0 +1,151 @@
+import type {
+  PluginAssistantsApi,
+  PluginCliApi,
+  PluginHooksApi,
+  PluginMetricsApi,
+  PluginProjectsApi,
+  PluginTabsApi,
+  PluginWorkspacesApi,
+} from './daemon-api'
+import type { PluginHost, PluginManifest } from './manifest'
+import type { PluginActionsApi, PluginStoreApi, PluginUiApi } from './ui'
+
+/**
+ * Everything a plugin registers hands back one of these. The kernel calls
+ * every disposer a fiber collected before it re-imports the module, which is
+ * what makes hot reload safe by construction rather than by discipline.
+ */
+export type Disposer = () => void | Promise<void>
+
+export interface PluginLogger {
+  debug: (message: string, data?: Record<string, unknown>) => void
+  info: (message: string, data?: Record<string, unknown>) => void
+  warn: (message: string, data?: Record<string, unknown>) => void
+  error: (message: string, data?: Record<string, unknown>) => void
+}
+
+export interface PluginPaths {
+  /** The plugin's own directory — read-only as far as the plugin is concerned. */
+  root: string
+  /** `<profile>/plugins-config/<id>`: files a human is expected to edit. */
+  config: string
+  /** `<profile>/plugins-state/<id>`: caches, databases, anything disposable. */
+  state: string
+  /** `<state>/plugin.log`, where `ctx.log` and load failures are written. */
+  log: string
+}
+
+export type PluginEventListener<T = never> = (payload: T) => unknown
+
+/**
+ * Five dispatch modes, after Cordis. `emit` is the one you want unless you
+ * need a result: it never awaits and never lets one listener's rejection
+ * reach another.
+ */
+export interface PluginEventDispatch {
+  /** Fire and forget. Rejections are logged against the emitting plugin. */
+  emit: (event: string, payload?: unknown) => void
+  /** All listeners at once; resolves with every result. */
+  parallel: (event: string, payload?: unknown) => Promise<unknown[]>
+  /** One listener at a time, in registration order. */
+  serial: (event: string, payload?: unknown) => Promise<unknown[]>
+  /** Stops at the first listener returning something other than `undefined`. */
+  bail: <T>(event: string, payload?: unknown) => Promise<T | undefined>
+  /** Threads a value through every listener; each returns the next input. */
+  waterfall: <T>(event: string, value: T) => Promise<T>
+}
+
+/**
+ * Talk to this plugin's other half. `call` crosses the process boundary
+ * (UI ⇄ daemon) over aimux's existing IPC socket; the payload is opaque to
+ * the protocol, which validates the envelope once and never the contents.
+ *
+ * A plugin with only one half still gets `rpc` — `call` simply rejects with
+ * "no handler", which is also what an unhandled verb does.
+ */
+export interface PluginRpc {
+  call: <T = unknown>(verb: string, payload?: unknown) => Promise<T>
+  handle: (verb: string, handler: (payload: unknown) => unknown) => Disposer
+  /** One-way fanout to every live instance of the other half. */
+  broadcast: (verb: string, payload?: unknown) => void
+}
+
+/**
+ * The object a plugin's `apply` receives. Services beyond this base
+ * (`ctx.ui.*`, `ctx.assistants`, `ctx.tabs`…) arrive in later API phases and
+ * are always reached through `inject`, so a plugin that asks for one it does
+ * not get stays `pending` instead of crashing.
+ */
+export interface PluginContext {
+  readonly id: string
+  readonly manifest: PluginManifest
+  /** Which process this half is running in. */
+  readonly host: PluginHost
+  readonly log: PluginLogger
+  /** Merged and defaulted from the manifest schema, the registry and user config. */
+  readonly config: Record<string, unknown>
+  readonly paths: PluginPaths
+  readonly rpc: PluginRpc
+
+  /**
+   * Register teardown. The setup function runs immediately (awaited when it
+   * returns a promise); the disposer it returns runs on unload, in reverse
+   * registration order. Anything a plugin allocates — a timer, a watcher, a
+   * socket — belongs in here.
+   */
+  effect: (setup: () => Disposer | void | Promise<Disposer | void>) => void
+
+  /** Subscribe to a host or plugin event. Auto-disposed on unload. */
+  on: <T = unknown>(event: string, listener: PluginEventListener<T>) => Disposer
+
+  emit: PluginEventDispatch['emit']
+  parallel: PluginEventDispatch['parallel']
+  serial: PluginEventDispatch['serial']
+  bail: PluginEventDispatch['bail']
+  waterfall: PluginEventDispatch['waterfall']
+
+  /**
+   * Publish a service other plugins may `inject`. Withdrawn automatically on
+   * unload, which unloads whoever injected it.
+   */
+  provide: (name: string, value: unknown) => void
+  /** Read a service. Prefer `inject` — it makes the dependency load-ordered. */
+  service: <T = unknown>(name: string) => T | undefined
+}
+
+/**
+ * The UI half's context. `ui`, `actions` and `store` are attached by the UI
+ * host; a plugin declaring `entries.ui` always receives them.
+ */
+export interface UiPluginContext<Slice = unknown> extends PluginContext {
+  readonly host: 'ui'
+  readonly ui: PluginUiApi
+  readonly actions: PluginActionsApi
+  readonly store: PluginStoreApi<Slice>
+}
+
+/**
+ * The daemon half's context. Attached by the daemon host; a plugin declaring
+ * `entries.daemon` always receives them.
+ */
+export interface DaemonPluginContext extends PluginContext {
+  readonly host: 'daemon'
+  readonly tabs: PluginTabsApi
+  readonly projects: PluginProjectsApi
+  readonly workspaces: PluginWorkspacesApi
+  readonly assistants: PluginAssistantsApi
+  readonly hooks: PluginHooksApi
+  readonly cli: PluginCliApi
+  readonly metrics: PluginMetricsApi
+}
+
+export interface PluginDefinition<Ctx extends PluginContext = PluginContext> {
+  /** Diagnostic label. Defaults to the manifest id plus the half. */
+  name?: string
+  /**
+   * Services this half needs. The fiber stays `pending` until every one is
+   * provided, then applies; if one is later withdrawn the fiber unloads.
+   */
+  inject?: readonly string[]
+  apply: (ctx: Ctx) => void | Promise<void>
+}