@brimveyn/aimux 1.21.0 → 1.22.2

package/src/settings/sections/notifications.ts

@@ -0,0 +1,99 @@
+import type { SettingOption, SettingSection } from '../types'
+
+import {
+  BUILTIN_SOUND_IDS,
+  DEFAULT_VOLUME,
+  getCustomSoundsDir,
+  listCustomSoundIds,
+  playSoundFile,
+  resolveSoundPath,
+  SOUND_OFF,
+} from '../../platform/play-sound'
+import { toast } from '../../state/toast-store'
+import { settingsStore } from '../settings-store'
+
+/** Spelled once, here, next to the rows that own them. */
+const NOTIFICATION_SOUND = 'notifications.sound'
+const NOTIFICATION_VOLUME = 'notifications.volume'
+
+/**
+ * `off` plus the shipped three plus whatever is in the drop-in directory. Built
+ * once, at import: a settings row's options are part of the schema (hydration
+ * validates the stored value against them), so they cannot depend on a scan that
+ * happens per render. A newly dropped file therefore shows up on the next
+ * launch, which the row's description says out loud.
+ */
+const SOUND_OPTIONS: SettingOption[] = [
+  { label: 'off', value: SOUND_OFF },
+  ...BUILTIN_SOUND_IDS.map((id) => ({ label: id, value: id })),
+  ...listCustomSoundIds().map((id) => ({ label: id, value: id })),
+]
+
+/** The selected sound id, or `off`. */
+function selectedSoundId(): string {
+  const value = settingsStore.getState().values[NOTIFICATION_SOUND]
+  return typeof value === 'string' ? value : SOUND_OFF
+}
+
+function selectedVolume(): number {
+  const value = settingsStore.getState().values[NOTIFICATION_VOLUME]
+  return typeof value === 'number' ? value : DEFAULT_VOLUME
+}
+
+/**
+ * Play the configured notification sound, if any. Silent — and cheap — when the
+ * user has set the row to `off`, which is what makes it safe to call on every
+ * status edge.
+ */
+export function playNotificationSound(options?: { ignoreThrottle?: boolean }): boolean {
+  const path = resolveSoundPath(selectedSoundId())
+  if (path == null) return false
+  return playSoundFile(path, { ...options, volume: selectedVolume() })
+}
+
+export const NOTIFICATIONS_SECTION: SettingSection = {
+  description: 'Plays when an assistant needs an answer, or finishes a turn.',
+  id: 'notifications',
+  label: 'Notifications',
+  rows: [
+    {
+      description: `"off" disables it. Drop your own in ${getCustomSoundsDir()} — picked up at the next launch.`,
+      fallback: 'plane',
+      id: NOTIFICATION_SOUND,
+      kind: 'select',
+      label: 'Sound',
+      options: SOUND_OPTIONS,
+      storage: 'settings',
+    },
+    {
+      description:
+        "Percent of the file's own level. Ignored by `aplay` and by Windows, which play at the system volume.",
+      fallback: DEFAULT_VOLUME,
+      id: NOTIFICATION_VOLUME,
+      kind: 'number',
+      label: 'Volume',
+      max: 100,
+      min: 0,
+      step: 5,
+      storage: 'settings',
+    },
+    {
+      // The one way to find out that this machine has no audio player before a
+      // notification you actually cared about goes silent.
+      description: 'Play the selected sound now.',
+      id: 'notifications.test',
+      kind: 'action',
+      label: 'Test sound',
+      run: () => {
+        if (selectedSoundId() === SOUND_OFF) {
+          toast.info('Notification sound is off')
+          return
+        }
+        if (!playNotificationSound({ ignoreThrottle: true })) {
+          toast.error('Could not play that sound — no audio player found')
+        }
+      },
+      value: () => selectedSoundId(),
+    },
+  ],
+}

package/src/settings/sections/setup.ts

@@ -0,0 +1,54 @@
+import type { ProjectRecord } from '../../state/types'
+import type { SettingRow, SettingSection } from '../types'
+
+import { runSideEffectGlobal } from '../../state/dispatch-ref'
+import { readSetupScriptLines, writeSetupCommand } from '../../state/project-data'
+
+const SETUP_ROW_PREFIX = 'setup.script.'
+
+/**
+ * One row per project, over the setup script at
+ * `~/.config/aimux/<profile>/projects/<id>/setup.sh`.
+ *
+ * A script whose work is a single command is editable here, which is the case
+ * this section exists for — `bun install && cp .env.example .env` should not
+ * require opening an editor. A script with more than one line of work is shown
+ * but not editable: a one-line field cannot round-trip it, and overwriting it
+ * from here would destroy whatever was there. Those hand over to the editor
+ * instead.
+ */
+function setupRow(projectId: string, projectName: string): SettingRow {
+  const lines = readSetupScriptLines(projectId)
+
+  if (lines.length > 1) {
+    return {
+      description: `${String(lines.length)} lines — too much for one field. Opens your editor.`,
+      id: `${SETUP_ROW_PREFIX}${projectId}`,
+      kind: 'action',
+      label: projectName,
+      run: () => runSideEffectGlobal({ projectId, type: 'configure-setup-script' }),
+      value: () => `${String(lines.length)} lines ›`,
+    }
+  }
+
+  return {
+    description: 'Runs once in each new workspace, from its root.',
+    id: `${SETUP_ROW_PREFIX}${projectId}`,
+    kind: 'text',
+    label: projectName,
+    placeholder: 'nothing yet',
+    // The file, not the state: this is the only row whose value lives on disk,
+    // and the screen re-reads it after every write.
+    read: () => lines[0] ?? '',
+    storage: 'app',
+    write: (value) => writeSetupCommand(projectId, String(value)),
+  }
+}
+
+export const SETUP_SECTION: SettingSection = {
+  id: 'setup',
+  label: 'Setup',
+  rowCount: (projects) => projects.length,
+  rows: (projects: readonly ProjectRecord[]) =>
+    projects.map((project) => setupRow(project.id, project.name)),
+}

package/src/settings/sections/status-bar.ts

@@ -0,0 +1,63 @@
+import { setStatusBarSeparator, type StatusBarSeparator } from '@brimveyn/aimux-config'
+
+import type { SettingSection } from '../types'
+
+export const AI_USAGE_ENABLED = 'statusBar.aiUsage.enabled'
+export const AI_USAGE_POLL_SECONDS = 'statusBar.aiUsage.pollSeconds'
+
+const SEPARATORS: { value: StatusBarSeparator; label: string }[] = [
+  { label: 'arrow', value: 'arrow' },
+  { label: 'round', value: 'round' },
+  { label: 'slant', value: 'slant' },
+  { label: 'flame', value: 'flame' },
+  { label: 'none', value: 'none' },
+]
+
+/**
+ * `statusBar.aiUsage.tools` is not here: it is a list, and this screen has no row
+ * kind for one. `claudePlan` and `codexWeeklyLimit` are not here either — they are
+ * declared in the config type but read nowhere, and a row that does nothing is
+ * worse than no row.
+ */
+export const STATUS_BAR_SECTION: SettingSection = {
+  id: 'statusBar',
+  label: 'Status bar',
+  rows: [
+    {
+      apply: (value) => setStatusBarSeparator(value as StatusBarSeparator),
+      description: 'Glyph between sections. All but "none" need a nerd font.',
+      fallback: 'arrow',
+      fromConfig: (config) => config.statusBar?.separator,
+      id: 'statusBar.separator',
+      kind: 'select',
+      label: 'Separator',
+      options: SEPARATORS,
+      storage: 'settings',
+    },
+    {
+      description: 'Show how much of your Claude or Codex quota is left.',
+      fallback: false,
+      fromConfig: (config) => config.statusBar?.aiUsage?.enabled,
+      id: AI_USAGE_ENABLED,
+      kind: 'toggle',
+      label: 'AI usage indicator',
+      storage: 'settings',
+    },
+    {
+      // The floor is 180 rather than a warning at 180: Claude's endpoint answers
+      // a faster caller with a rate limit, and the symptom is an indicator that
+      // quietly stops updating. A setting whose own description tells you not to
+      // use half its range should not have that half.
+      description: "Seconds between checks. Claude's endpoint rate-limits anything faster.",
+      fallback: 180,
+      fromConfig: (config) => config.statusBar?.aiUsage?.pollSeconds,
+      id: AI_USAGE_POLL_SECONDS,
+      kind: 'number',
+      label: 'Refresh interval',
+      max: 3_600,
+      min: 180,
+      step: 60,
+      storage: 'settings',
+    },
+  ],
+}

package/src/settings/settings-store.ts

@@ -0,0 +1,207 @@
+import type { AimuxUserConfig } from '@brimveyn/aimux-config'
+
+import { useStore } from 'zustand'
+import { createStore } from 'zustand/vanilla'
+
+import type {
+  SettingCtx,
+  SettingRow,
+  SettingValue,
+  StoredSettingRow,
+  StoredSettings,
+} from './types'
+
+import { loadConfig, saveConfig } from '../config'
+import { logDebug } from '../debug/input-log'
+import { toast } from '../state/toast-store'
+
+export interface SettingsState {
+  /** Bumped by every write. Rows whose value lives in a file have no other way
+   *  to tell the screen to look again. */
+  revision: number
+  /** Effective value per row id, for the rows the settings screen owns. */
+  values: StoredSettings
+  /**
+   * Rows the user's `aimux.config.ts` declares. Their value comes back from that
+   * file at every launch, so an edit made here is good for this session only.
+   */
+  fromConfigFile: ReadonlySet<string>
+  /**
+   * Rows this screen has a value written for. Not the same as "differs from the
+   * default" — someone may have set a row back to its default value — but it is
+   * what "reset" removes, so it is what the marker has to mean.
+   */
+  touched: ReadonlySet<string>
+  /**
+   * What each row would hold if this screen had never touched it: the config
+   * file's value where it declares one, else the built-in default. Resolved once,
+   * at hydration, because that is when the config file was read — recomputing it
+   * later would read a file the rest of the app has not.
+   */
+  defaults: StoredSettings
+}
+
+const EMPTY_FROM_CONFIG: ReadonlySet<string> = new Set()
+
+export const settingsStore = createStore<SettingsState>(() => ({
+  defaults: {},
+  fromConfigFile: EMPTY_FROM_CONFIG,
+  revision: 0,
+  touched: EMPTY_FROM_CONFIG,
+  values: {},
+}))
+
+export function useSettingsStore<T>(selector: (state: SettingsState) => T): T {
+  return useStore(settingsStore, selector)
+}
+
+/**
+ * A value a row publishes is one that row can actually hold, wherever it came
+ * from. Everything the screen writes is already in range; `aimux.config.ts` and a
+ * hand-edited (or older) `aimux.json` are not, and an unchecked one shows the row
+ * saying 60 while the code reading it uses its own floor of 180 — or shows a raw
+ * `wavy` where a separator name belongs.
+ *
+ * A number is clamped to its range. An option outside the list has no ordering to
+ * be clamped along, so the only value in the set that means anything is the row's
+ * own default, which `settings-schema.test.ts` keeps inside it.
+ *
+ * The range is the envelope for a setting this screen owns. The config file keeps
+ * its full reach over everything the screen has no row for.
+ */
+function withinRowDomain(row: StoredSettingRow, value: SettingValue): SettingValue {
+  if (row.kind === 'number' && typeof value === 'number') {
+    return Math.min(row.max, Math.max(row.min, value))
+  }
+  if (row.kind === 'select' && !row.options.some((option) => option.value === value)) {
+    return row.fallback
+  }
+  return value
+}
+
+/**
+ * Resolve every stored row and publish the result: the config file wins, then
+ * whatever the settings screen last wrote, then the built-in default. The config
+ * file is re-read at every launch, which is what makes its value the one that
+ * comes back — see `docs/guide/settings.md`.
+ *
+ * The schema is a parameter rather than an import so this module stays downstream
+ * of the sections, which read from it.
+ */
+export function hydrateSettings(rows: readonly SettingRow[], userConfig: AimuxUserConfig): void {
+  const stored = loadConfig().settings ?? {}
+  const values: StoredSettings = {}
+  const defaults: StoredSettings = {}
+  const fromConfigFile = new Set<string>()
+
+  for (const row of rows) {
+    const owned = storedRow(row)
+    if (!owned) continue
+    const declared = owned.fromConfig?.(userConfig)
+    if (declared !== undefined) fromConfigFile.add(owned.id)
+    defaults[owned.id] = withinRowDomain(owned, declared ?? owned.fallback)
+    const value = withinRowDomain(owned, declared ?? stored[owned.id] ?? owned.fallback)
+    values[owned.id] = value
+    // Unconditional: the caller has already applied the config file's own values
+    // (they are the baseline), and re-applying the same value is a no-op. What
+    // matters is that a value coming from `stored` reaches the running app.
+    owned.apply?.(value)
+  }
+
+  settingsStore.setState((state) => ({
+    defaults,
+    fromConfigFile,
+    revision: state.revision + 1,
+    touched: new Set(Object.keys(stored)),
+    values,
+  }))
+}
+
+/**
+ * Persist one value and apply it live. The merge reads the file rather than the
+ * store: the store holds resolved values, so merging from it would bake a value
+ * that came from `aimux.config.ts` into the JSON, where it would outlive the
+ * config-file line it came from.
+ */
+function persist(id: string, value: SettingValue | undefined): boolean {
+  const config = loadConfig()
+  const settings: StoredSettings = { ...config.settings }
+  if (value === undefined) delete settings[id]
+  else settings[id] = value
+  if (saveConfig({ ...config, settings })) return true
+  // Loud, not just logged: a read-only config directory or a full disk otherwise
+  // shows up as a key that does nothing, with no explanation anywhere.
+  logDebug('settings.write.failed', { id })
+  toast.error('Could not save that setting — see `aimux doctor`')
+  return false
+}
+
+/**
+ * The row as something with a key of its own, or nothing. Every operation that
+ * touches the `settings` block — hydrating it, resetting a key, saying a value
+ * needs a restart — asks this rather than narrowing the union by hand for the
+ * fourth time.
+ */
+export function storedRow(row: SettingRow): StoredSettingRow | null {
+  if (row.kind === 'info' || row.kind === 'action') return null
+  return row.storage === 'settings' ? row : null
+}
+
+export function readRow(row: SettingRow, ctx: SettingCtx): SettingValue {
+  if (row.kind === 'info' || row.kind === 'action') return row.value(ctx)
+  if (row.storage === 'app') return row.read(ctx)
+  return ctx.values[row.id] ?? row.fallback
+}
+
+/**
+ * Writing the value a row already has does nothing. That is not just an
+ * optimisation: an `app` row delegates to the action behind the keybinding, and
+ * several of those toggle rather than set — so handing one a value it already
+ * holds would flip it the wrong way. One rule here beats a guard per row.
+ */
+export function writeRow(row: SettingRow, value: SettingValue, ctx: SettingCtx): void {
+  if (row.kind === 'info' || row.kind === 'action') return
+  if (readRow(row, ctx) === value) return
+  if (row.storage === 'app') {
+    row.write(value, ctx)
+    bumpRevision()
+    return
+  }
+  if (!persist(row.id, value)) return
+  settingsStore.setState((state) => ({
+    revision: state.revision + 1,
+    touched: new Set(state.touched).add(row.id),
+    values: { ...state.values, [row.id]: value },
+  }))
+  row.apply?.(value)
+}
+
+/**
+ * Forget what this screen wrote for a row and go back to what the row would have
+ * been without it: the config file's value if it declares one, else the built-in
+ * default. Only the rows this screen owns — an `app` row's value has its own home
+ * and its own idea of a default.
+ */
+export function resetRow(row: SettingRow): void {
+  const owned = storedRow(row)
+  if (!owned) return
+  if (!settingsStore.getState().touched.has(owned.id)) return
+  if (!persist(owned.id, undefined)) return
+
+  const value = settingsStore.getState().defaults[owned.id] ?? owned.fallback
+  settingsStore.setState((state) => {
+    const touched = new Set(state.touched)
+    touched.delete(owned.id)
+    return { revision: state.revision + 1, touched, values: { ...state.values, [owned.id]: value } }
+  })
+  owned.apply?.(value)
+}
+
+/**
+ * Tells the screen that what it is showing may be out of date. Needed because a
+ * row's value can live outside both stores — the setup script is a file — and
+ * nothing else would make the list read it again.
+ */
+function bumpRevision(): void {
+  settingsStore.setState((state) => ({ revision: state.revision + 1 }))
+}

package/src/settings/types.ts

@@ -0,0 +1,108 @@
+import type { AimuxUserConfig } from '@brimveyn/aimux-config'
+
+import type { AppState, ProjectRecord } from '../state/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 whose value lives in the `settings` block of `aimux.json`. */
+export type StoredSettingRow = SettingRowBase & SettingKind & StoredRow
+
+export type SettingRow =
+  | StoredSettingRow
+  | (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
+  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/snippets/run-shell-var.ts

@@ -30,6 +30,13 @@ function buildShellArgv(cmd: string): string[] {
 export async function runShellVar(name: string, v: SnippetShellVar): Promise<string> {
   const requested = v.timeout ?? DEFAULT_TIMEOUT_MS
   const timeoutMs = Math.min(Math.max(requested, 0), MAX_TIMEOUT_MS)
+  const logFailure = (event: string, error: unknown): void => {
+    logDebug(event, {
+      cmd: v.sh,
+      error: error instanceof Error ? error.message : String(error),
+      name,
+    })
+  }
 
   let proc: Bun.Subprocess<'ignore', 'pipe', 'pipe'>
   try {
@@ -39,35 +46,55 @@ export async function runShellVar(name: string, v: SnippetShellVar): Promise<str
       stdout: 'pipe',
     })
   } catch (error) {
-    logDebug('snippets.shellVar.spawnError', {
-      cmd: v.sh,
-      error: error instanceof Error ? error.message : String(error),
-      name,
-    })
+    logFailure('snippets.shellVar.spawnError', error)
     return ''
   }
 
+  // Racing the timeout rather than checking a flag after the reads: `proc.kill()`
+  // signals the shell, but a command it forked instead of exec'ing outlives it
+  // still holding the stdout pipe, so reading to EOF blocks past the deadline —
+  // on Linux `sleep 5` behind an 80ms timeout waited the full five seconds.
+  // ponytail: the orphan is left running. Kill the process group if a snippet
+  // ever spawns something expensive enough to care about.
   let timeoutFired = false
-  const timeoutHandle = setTimeout(() => {
-    timeoutFired = true
+  let timeoutHandle: ReturnType<typeof setTimeout> | undefined
+  const expired = new Promise<'timeout'>((resolve) => {
+    timeoutHandle = setTimeout(() => {
+      timeoutFired = true
+      try {
+        proc.kill()
+      } catch {
+        // process already gone
+      }
+      resolve('timeout')
+    }, timeoutMs)
+  })
+
+  // Swallow inside, not with a trailing `.catch`: the loser of the race below
+  // is still a live promise, and a late failure would otherwise surface as an
+  // unhandled rejection long after we returned.
+  const collected = (async (): Promise<[string, string, number] | 'failed'> => {
     try {
-      proc.kill()
-    } catch {
-      // process already gone
+      return await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+        proc.exited,
+      ])
+    } catch (error) {
+      logFailure('snippets.shellVar.error', error)
+      return 'failed'
     }
-  }, timeoutMs)
+  })()
 
   try {
-    const [stdout, stderr, exitCode] = await Promise.all([
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
-      proc.exited,
-    ])
+    const outcome = await Promise.race([collected, expired])
 
-    if (timeoutFired) {
+    if (outcome === 'timeout' || timeoutFired) {
       logDebug('snippets.shellVar.timeout', { cmd: v.sh, name, timeoutMs })
       return ''
     }
+    if (outcome === 'failed') return ''
+    const [stdout, stderr, exitCode] = outcome
 
     if (exitCode !== 0) {
       logDebug('snippets.shellVar.nonZeroExit', {
@@ -81,11 +108,10 @@ export async function runShellVar(name: string, v: SnippetShellVar): Promise<str
 
     return v.trim === false ? stdout : stdout.replace(/\s+$/, '')
   } catch (error) {
-    logDebug('snippets.shellVar.error', {
-      cmd: v.sh,
-      error: error instanceof Error ? error.message : String(error),
-      name,
-    })
+    // Belt and braces: nothing in the try can reject today (`collected` swallows
+    // its own errors, `expired` never rejects), but this runs arbitrary user
+    // shell and the contract is that it never throws at its caller.
+    logFailure('snippets.shellVar.error', error)
     return ''
   } finally {
     clearTimeout(timeoutHandle)