@brimveyn/aimux-config 0.10.9 → 0.11.0

package/src/index.ts

@@ -5,15 +5,19 @@ export * as actions from './actions'
 
 // TUI theme system (1:1 port of opencode TUI).
 export {
+  BUILTIN_THEME_IDS,
   type ClaudeThemeFile,
+  clearRuntimeThemes,
+  getTuiTheme,
   isKnownThemeId,
   migrateThemeId,
+  registerTuiTheme,
   resolveClaudeTheme,
   type ResolvedTuiTheme,
   resolveTuiTheme,
   type RGBA,
-  THEME_IDS,
   type ThemeId,
+  themeIds,
   type ThemeMode,
   TUI_COLOR_TOKENS,
   TUI_THEMES,
@@ -28,6 +32,13 @@ export { GroupBuilder, KeymapBuilder, ModeBindingBuilder } from './keymap-builde
 export { getDefaultKeymapConfig } from './defaults'
 export { resolveConfig } from './resolver'
 export { isAutoCommitEnabled, setAutoCommitEnabled } from './auto-commit-runtime'
+export {
+  clearPluginActions,
+  hasPluginAction,
+  pluginAction,
+  pluginActionNames,
+  registerPluginAction,
+} from './plugin-actions-runtime'
 export { getMultiRepoConfig, setMultiRepoConfig } from './multi-repo-runtime'
 export { getStatusBarSeparator, setStatusBarSeparator } from './status-bar-runtime'
 export {
@@ -38,6 +49,13 @@ export {
 } from './external-editor-runtime'
 export { DEFAULT_MULTI_REPO_CONFIG } from './defaults'
 
+// The settings screen's row and section shapes; a plugin registers one.
+export type * from './settings-types'
+
+// The application state, mode and layout shapes. Defined in this package —
+// `src/` re-exports them rather than declaring its own copies.
+export type * from './app-types'
+
 // User-facing config types (keymap/backends/projects/etc.).
 export type {
   Action,
@@ -47,45 +65,38 @@ export type {
   AIUsageTool,
   AIUsageToolConfig,
   AppAction,
-  AppState,
   AutoCommitConfig,
   AutoRenameConfig,
   BackendConfig,
   BindingDef,
-  DiscoveredRepo,
   ExternalEditorConfig,
-  FocusMode,
-  GitFileListMode,
   GitPaneConfig,
-  GitPaneDiffCountConfig,
   GitPaneEmbeddedConfig,
   GitPanePaneConfig,
-  GitPanePathConfig,
-  GitPaneState,
   GroupBuilderApi,
   HooksConfig,
   KeyInput,
   KeymapBuilderApi,
   KeyResult,
+  LayoutLeaf,
+  LayoutLeafKind,
   LayoutNode,
-  ModalState,
+  LayoutSplit,
   ModeBindingBuilderApi,
   ModeContext,
   ModeId,
   ModeKeymapDef,
   MultiRepoConfig,
-  MultiRepoState,
-  ProjectRecord,
+  PluginConfigDecl,
+  PluginConfigEntry,
   ResolvedConfig,
   ResolvedKeymapConfig,
   SidebarConfig,
   SideEffect,
   SnippetDef,
-  SnippetRecord,
   SnippetShellVar,
   SnippetVar,
   SplitDirection,
   StatusBarConfig,
   StatusBarSeparator,
-  TabSession,
 } from './types'

package/src/keymap-builder.ts

@@ -10,6 +10,8 @@ import type {
   ResolvedKeymapConfig,
 } from './types'
 
+import { pluginAction } from './plugin-actions-runtime'
+
 // ---------------------------------------------------------------------------
 // GroupBuilder — sugar for <leader>-prefixed sub-trees
 // ---------------------------------------------------------------------------
@@ -101,6 +103,10 @@ export class KeymapBuilder implements KeymapBuilderApi {
     return this
   }
 
+  plugin(name: string): Action {
+    return pluginAction(name)
+  }
+
   mode(
     id: ModeId | readonly ModeId[],
     configure: (m: ModeBindingBuilderApi) => ModeBindingBuilderApi

package/src/plugin-actions-runtime.ts

@@ -0,0 +1,50 @@
+import type { ActionFn, KeyResult, ModeContext } from './types'
+
+/**
+ * Named actions a plugin contributes, so a user's keymap can bind one by name
+ * before the plugin that answers it has loaded — or at all.
+ *
+ * A keymap is resolved at startup from `aimux.config.ts`, and plugins load
+ * after that. Binding a function directly would mean the config file could
+ * only reference plugins it imported, which is exactly the coupling a plugin
+ * system is supposed to remove. Binding a *name* defers the lookup to the
+ * moment the key is pressed.
+ *
+ * Lives in this package, alongside the other runtime singletons
+ * (`auto-commit-runtime`, `multi-repo-runtime`), because that is where the
+ * action factories a config file calls already are.
+ */
+
+/** Qualified `<pluginId>.<verb>` — the id a keymap writes. */
+const handlers = new Map<string, ActionFn>()
+
+export function registerPluginAction(name: string, handler: ActionFn): () => void {
+  handlers.set(name, handler)
+  return () => {
+    if (handlers.get(name) === handler) handlers.delete(name)
+  }
+}
+
+/** Test seam. Never called by the app. */
+export function clearPluginActions(): void {
+  handlers.clear()
+}
+
+export function pluginActionNames(): string[] {
+  return [...handlers.keys()]
+}
+
+export function hasPluginAction(name: string): boolean {
+  return handlers.has(name)
+}
+
+/**
+ * The `Action` a keymap binds. Resolved on every keypress rather than at
+ * registration: a plugin that is not loaded yet, is disabled, or failed simply
+ * yields `null`, which is the same "this key does nothing here" a mode with no
+ * binding produces. Anything louder would turn one broken plugin into a broken
+ * keyboard.
+ */
+export function pluginAction(name: string): ActionFn {
+  return (ctx: ModeContext): KeyResult | null => handlers.get(name)?.(ctx) ?? null
+}

package/src/resolver.ts

@@ -5,6 +5,8 @@ import type {
   ModeId,
   ModeKeymapDef,
   MultiRepoConfig,
+  PluginConfigDecl,
+  PluginConfigEntry,
   ResolvedConfig,
   ResolvedKeymapConfig,
 } from './types'
@@ -60,6 +62,7 @@ export function resolveConfig(userConfig: AimuxUserConfig): ResolvedConfig {
     integrations: resolveIntegrations(userConfig.integrations),
     keymaps,
     multiRepo,
+    plugins: resolvePlugins(userConfig.plugins),
     // ponytail: `sessionBar` is the pre-rename key. Unknown keys parse
     // silently, so without the fallback the setting just vanishes.
     projectBar: resolveProjectBar(userConfig.projectBar ?? userConfig.sessionBar),
@@ -71,6 +74,25 @@ export function resolveConfig(userConfig: AimuxUserConfig): ResolvedConfig {
   }
 }
 
+/**
+ * Normalises the shorthand. A declaration with neither `path` nor `id` names
+ * nothing loadable, so it is dropped here rather than becoming a mystery
+ * "plugin not found" at load time.
+ */
+function resolvePlugins(declarations: PluginConfigDecl[] | undefined): PluginConfigEntry[] {
+  if (!declarations) return []
+  const entries: PluginConfigEntry[] = []
+  for (const declaration of declarations) {
+    if (typeof declaration === 'string') {
+      if (declaration.trim() !== '') entries.push({ path: declaration })
+      continue
+    }
+    if (declaration.path === undefined && declaration.id === undefined) continue
+    entries.push(declaration)
+  }
+  return entries
+}
+
 function resolveIntegrations(
   userConfig: AimuxUserConfig['integrations']
 ): ResolvedConfig['integrations'] {

package/src/settings-types.ts

@@ -0,0 +1,160 @@
+// -----------------------------------------------------------------------------
+// The settings screen's row and section shapes.
+//
+// In this package rather than in `src/` because a plugin registers a settings
+// section, and a plugin has to be able to type one without depending on the
+// aimux binary. `src/settings/types.ts` re-exports from here.
+// -----------------------------------------------------------------------------
+
+import type { AppState, ProjectRecord } from './app-types'
+import type { AimuxUserConfig } from './types'
+
+export type SettingValue = boolean | number | string
+
+/**
+ * The values the settings screen owns, keyed by row id. Sparse on purpose: a
+ * missing key means "never touched", which is not the same as `false`.
+ */
+export type StoredSettings = Record<string, SettingValue>
+
+export interface SettingCtx {
+  state: AppState
+  values: StoredSettings
+}
+
+export interface SettingOption {
+  value: SettingValue
+  label: string
+}
+
+/** How a row draws itself, and what activating it does. */
+type SettingKind =
+  | { kind: 'toggle' }
+  | { kind: 'select'; options: readonly SettingOption[] }
+  | { kind: 'number'; min: number; max: number; step: number }
+  /** Activating it opens a one-field modal. Empty means "unset", not "empty string". */
+  | { kind: 'text'; placeholder?: string }
+
+interface SettingRowBase {
+  id: string
+  label: string
+  description?: string
+}
+
+/**
+ * A row with no other home for its value: it lives in the `settings` block of
+ * `aimux.json`, and `readRow`/`writeRow` reach it by id. Nothing here repeats
+ * the id, so a row can't read one key and write another.
+ */
+interface StoredRow {
+  storage: 'settings'
+  /** Used when neither the config file nor the settings screen has a value. */
+  fallback: SettingValue
+  /**
+   * The value the user's `aimux.config.ts` declares for this row, or undefined
+   * when it doesn't declare it. Declared means it wins at every startup — a UI
+   * edit then lasts until the next launch, and the row says so.
+   */
+  fromConfig?: (config: AimuxUserConfig) => SettingValue | undefined
+  /**
+   * Hands a new value to whatever owns it in the running app. Not every live row
+   * needs one — a value whose only reader subscribes to this store is live on its
+   * own, which is why "needs a restart" is declared rather than inferred.
+   */
+  apply?: (value: SettingValue) => void
+  /** The running app won't see the new value; the row says so. */
+  restart?: true
+}
+
+/**
+ * A view over a value `AppState` already owns (git pane preferences, bar
+ * visibility, …). It delegates to that value's existing action or side effect
+ * rather than keeping a second copy.
+ */
+interface DerivedRow {
+  storage: 'app'
+  read: (ctx: SettingCtx) => SettingValue
+  /** Same context `read` gets, so a write that has to merge into a record can. */
+  write: (value: SettingValue, ctx: SettingCtx) => void
+}
+
+/**
+ * A row over one key of a plugin's configuration.
+ *
+ * Not a `settings` row: that block of `aimux.json` is never read by plugin
+ * discovery, so a value written there would silently reach no plugin. Not an
+ * `app` row either — its value has neither a home in `AppState` nor a place in
+ * the settings screen's hydration, and the two marks a plugin row most needs
+ * (`~` the registry has an override, `*` `aimux.config.ts` declares it and
+ * keeps winning) come from the plugin's own layers rather than from this
+ * screen's bookkeeping.
+ *
+ * The three functions are closures, like `DerivedRow`'s: the settings store
+ * must not learn how to reach a plugin registry.
+ */
+interface PluginConfigRow {
+  storage: 'plugin'
+  /** For the detail view, and for a test to name the row it means. */
+  pluginId: string
+  field: string
+  /** Never rendered and edited from empty. */
+  secret?: boolean
+  /** `aimux.config.ts` declares this key and keeps winning. Drives `*`. */
+  fromConfigFile: boolean
+  /** A layer above the manifest default set it. Drives `~`. */
+  isSet: boolean
+  read: () => SettingValue
+  write: (value: SettingValue) => void
+  /** Drop the override and fall back through the layers underneath. */
+  reset: () => void
+}
+
+/** A row whose value lives in the `settings` block of `aimux.json`. */
+export type StoredSettingRow = SettingRowBase & SettingKind & StoredRow
+
+/** A row over one key of a plugin's config. Narrowed by `storage === 'plugin'`. */
+export type PluginSettingRow = SettingRowBase & SettingKind & PluginConfigRow
+
+export type SettingRow =
+  | StoredSettingRow
+  | PluginSettingRow
+  | (SettingRowBase & SettingKind & DerivedRow)
+  | (SettingRowBase & { kind: 'info'; value: (ctx: SettingCtx) => string })
+  /**
+   * Not a setting: a button. For the things a row cannot hold — a multi-line
+   * script, a list — where the honest move is to hand over to whatever can.
+   */
+  | (SettingRowBase & { kind: 'action'; value: (ctx: SettingCtx) => string; run: () => void })
+
+export interface SettingSection {
+  id: string
+  /**
+   * One cell, text presentation, present in the base fonts — the same rule the
+   * stats screen's section glyphs follow, so the eye finds a section by shape
+   * before it reads the label.
+   *
+   * Required, and on the section rather than in a lookup keyed by id: a map
+   * would need a fallback, and a fallback turns a renamed or added section into
+   * a silent placeholder instead of a compile error.
+   */
+  glyph: string
+  label: string
+  /** Shown once under the section's title, for a caveat that covers every row. */
+  description?: string
+  /**
+   * A function when the rows depend on the projects — one row per project, say.
+   * The projects and nothing else: a builder handed the whole state would be free
+   * to depend on anything in it, and every caller would have to have all of it.
+   *
+   * Building a row may cost something (Setup reads a script off disk), so anything
+   * that only needs to know *how many* rows there are asks `rowCount` instead.
+   */
+  rows: SettingRow[] | ((projects: readonly ProjectRecord[]) => SettingRow[])
+  /**
+   * How many rows there will be, without building them. Required alongside a
+   * dynamic `rows`, and kept honest by `settings-schema.test.ts`: the reducer
+   * clamps the cursor with this, and a count that disagrees with the list is a
+   * cursor that stops one row short of the end, or one past it.
+   */
+  rowCount?: (projects: readonly ProjectRecord[]) => number
+}

package/src/tui/index.ts

@@ -1,4 +1,14 @@
-export { isKnownThemeId, migrateThemeId, THEME_IDS, type ThemeId, TUI_THEMES } from './registry'
+export {
+  BUILTIN_THEME_IDS,
+  clearRuntimeThemes,
+  getTuiTheme,
+  isKnownThemeId,
+  migrateThemeId,
+  registerTuiTheme,
+  type ThemeId,
+  themeIds,
+  TUI_THEMES,
+} from './registry'
 export { type ClaudeThemeFile, resolveClaudeTheme, resolveTuiTheme } from './resolve'
 export { type TuiShikiOptions, tuiThemeToShiki } from './shiki'
 export { TUI_COLOR_TOKENS, type TuiColorToken } from './tokens'

package/src/tui/registry.ts

@@ -76,12 +76,55 @@ export const TUI_THEMES: Record<string, TuiThemeJson> = {
   'zenburn': zenburn as TuiThemeJson,
 }
 
-export type ThemeId = keyof typeof TUI_THEMES
+/**
+ * A shipped theme id. Widened with `(string & {})` because a theme can also be
+ * registered at runtime — from `<profile>/themes/` or by a plugin — and those
+ * ids are not knowable here. The literal half survives, so autocomplete still
+ * lists the shipped ones.
+ */
+export type ThemeId = keyof typeof TUI_THEMES | (string & {})
 
-export const THEME_IDS: ThemeId[] = Object.keys(TUI_THEMES).sort() as ThemeId[]
+/** Ids aimux ships, sorted. Runtime-registered ones are not in here. */
+export const BUILTIN_THEME_IDS: string[] = Object.keys(TUI_THEMES).sort()
+
+const runtimeThemes = new Map<string, TuiThemeJson>()
+
+/**
+ * Registers a theme loaded at runtime — a JSON file in `<profile>/themes/`, or
+ * one a plugin ships. Returns the disposer; unregistering a theme that is
+ * currently applied leaves the applied colours alone, since they were already
+ * resolved into the theme store.
+ *
+ * A runtime id may not shadow a shipped one: silently replacing `dracula`
+ * would make "which dracula?" depend on load order.
+ */
+export function registerTuiTheme(id: string, theme: TuiThemeJson): () => void {
+  if (id in TUI_THEMES) {
+    throw new Error(`theme "${id}" is shipped with aimux and cannot be replaced`)
+  }
+  runtimeThemes.set(id, theme)
+  return () => {
+    runtimeThemes.delete(id)
+  }
+}
+
+/** Test seam. Never called by the app. */
+export function clearRuntimeThemes(): void {
+  runtimeThemes.clear()
+}
+
+/** Every id the picker offers: shipped plus runtime-registered, sorted. */
+export function themeIds(): string[] {
+  if (runtimeThemes.size === 0) return BUILTIN_THEME_IDS
+  return [...BUILTIN_THEME_IDS, ...runtimeThemes.keys()].sort()
+}
+
+export function getTuiTheme(id: string): TuiThemeJson | undefined {
+  return TUI_THEMES[id] ?? runtimeThemes.get(id)
+}
 
 export function isKnownThemeId(id: string): id is ThemeId {
-  return id in TUI_THEMES
+  return id in TUI_THEMES || runtimeThemes.has(id)
 }
 
 const LEGACY_ID_MAP: Record<string, ThemeId> = {