@brimveyn/aimux 1.22.10 → 1.22.12

package/src/services/usage-history/stats.ts

@@ -0,0 +1,193 @@
+import { parseColor, RGBA } from '@opentui/core'
+
+import { emptyTokens, localDay, type UsageDays, type UsageTokens } from './store'
+
+/** Pure shaping of stored usage days into what the History page renders. */
+
+export interface HeatmapCell {
+  /** 'YYYY-MM-DD', or '' for a cell outside the covered range. */
+  day: string
+  level: number
+  value: number
+}
+
+function parseDay(key: string): Date {
+  const [year, month, day] = key.split('-').map(Number)
+  return new Date(year ?? 0, (month ?? 1) - 1, day ?? 1)
+}
+
+/** Whole days apart. Via `Date.UTC` on the calendar parts: a DST span is not a whole number of 24h periods. */
+function daysBetween(from: Date, to: Date): number {
+  const utcOf = (date: Date): number =>
+    Date.UTC(date.getFullYear(), date.getMonth(), date.getDate())
+  return Math.round((utcOf(to) - utcOf(from)) / 86_400_000)
+}
+
+/** Quartiles of the non-empty days: a linear `value / max` ramp lets one outlier flatten the year to level 1. */
+export function cutPoints(values: number[]): [number, number, number] {
+  const sorted = values.filter((value) => value > 0).sort((left, right) => left - right)
+  const at = (quantile: number): number =>
+    sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * quantile))] ?? 0
+  return [at(0.25), at(0.5), at(0.75)]
+}
+
+function levelOf(value: number, cuts: [number, number, number]): number {
+  if (value <= 0) return 0
+  if (value <= cuts[0]) return 1
+  if (value <= cuts[1]) return 2
+  if (value <= cuts[2]) return 3
+  return 4
+}
+
+/** Week columns needed to cover what is recorded, so the grid does not open on empty months. */
+export function coveredWeeks(days: UsageDays, today: Date, maxWeeks: number): number {
+  const dates = Object.keys(days).sort()
+  const first = dates[0]
+  if (first === undefined) return Math.min(maxWeeks, 12)
+  const elapsed = daysBetween(parseDay(first), today)
+  return Math.max(4, Math.min(maxWeeks, Math.ceil((elapsed + 1) / 7) + 1))
+}
+
+/** 7 rows (Monday first) by `weeks` columns, oldest left. Cells after today come back empty. */
+export function buildHeatmap(
+  counts: Record<string, number>,
+  weeks: number,
+  today: Date
+): HeatmapCell[][] {
+  const cuts = cutPoints(Object.values(counts))
+
+  // Anchored on the Sunday closing this week, so the last column is the week in progress.
+  const mondayIndex = (today.getDay() + 6) % 7
+  const end = new Date(today.getFullYear(), today.getMonth(), today.getDate() + (6 - mondayIndex))
+  // Calendar arithmetic, never `getTime() - n * DAY_MS`: across a DST change the
+  // millisecond form lands on 23:00 the day before and rotates every row by one.
+  const start = new Date(end.getFullYear(), end.getMonth(), end.getDate() - (weeks * 7 - 1))
+  const todayKey = localDay(today)
+
+  const rows: HeatmapCell[][] = []
+  for (let row = 0; row < 7; row++) {
+    const cells: HeatmapCell[] = []
+    for (let column = 0; column < weeks; column++) {
+      const date = new Date(
+        start.getFullYear(),
+        start.getMonth(),
+        start.getDate() + column * 7 + row
+      )
+      const key = localDay(date)
+      if (key > todayKey) {
+        cells.push({ day: '', level: 0, value: 0 })
+        continue
+      }
+      const value = counts[key] ?? 0
+      cells.push({ day: key, level: levelOf(value, cuts), value })
+    }
+    rows.push(cells)
+  }
+  return rows
+}
+
+/** Month initial over each column that opens a month. `cellWidth` mirrors the grid's own. */
+export function monthRuler(grid: HeatmapCell[][], weeks: number, cellWidth: number): string {
+  const initials = 'JFMAMJJASOND'
+  const chars: string[] = Array.from({ length: weeks * cellWidth }, () => ' ')
+  let previous = ''
+  for (let column = 0; column < weeks; column++) {
+    const day = grid[0]?.[column]?.day
+    if (day == null || day === '') continue
+    const month = day.slice(5, 7)
+    if (month !== previous) {
+      chars[column * cellWidth] = initials[Number(month) - 1] ?? ' '
+      previous = month
+    }
+  }
+  return chars.join('')
+}
+
+export function promptCounts(days: UsageDays): Record<string, number> {
+  const counts: Record<string, number> = {}
+  for (const [date, day] of Object.entries(days)) counts[date] = day.prompts
+  return counts
+}
+
+export interface UsageSummary {
+  branches: [string, number][]
+  /** Denominator for branch shares — branch-less entries are excluded. */
+  branchTotal: number
+  models: [string, number][]
+  modelTotal: number
+  peakPrompts: number
+  promptDays: number
+  /** Days carrying token data — a shorter span than `promptDays` once pruning starts. */
+  tokenDays: number
+  tokens: UsageTokens
+  totalPrompts: number
+}
+
+function rank(totals: Record<string, number>): { entries: [string, number][]; total: number } {
+  const entries = Object.entries(totals)
+  entries.sort((left, right) => right[1] - left[1])
+  let total = 0
+  for (const [, value] of entries) total += value
+  return { entries, total }
+}
+
+export function summarizeDays(days: UsageDays, limit = 6): UsageSummary {
+  const tokens = emptyTokens()
+  const models: Record<string, number> = {}
+  const branches: Record<string, number> = {}
+  let peakPrompts = 0
+  let promptDays = 0
+  let tokenDays = 0
+  let totalPrompts = 0
+
+  for (const day of Object.values(days)) {
+    tokens.cacheRead += day.tokens.cacheRead
+    tokens.cacheWrite += day.tokens.cacheWrite
+    tokens.input += day.tokens.input
+    tokens.output += day.tokens.output
+    tokens.total += day.tokens.total
+
+    if (day.tokens.total > 0) tokenDays += 1
+    if (day.prompts > 0) {
+      promptDays += 1
+      totalPrompts += day.prompts
+      if (day.prompts > peakPrompts) peakPrompts = day.prompts
+    }
+
+    for (const [model, count] of Object.entries(day.models)) {
+      models[model] = (models[model] ?? 0) + count
+    }
+    for (const [branch, count] of Object.entries(day.branches)) {
+      branches[branch] = (branches[branch] ?? 0) + count
+    }
+  }
+
+  const rankedModels = rank(models)
+  const rankedBranches = rank(branches)
+
+  return {
+    branches: rankedBranches.entries.slice(0, limit),
+    branchTotal: rankedBranches.total,
+    models: rankedModels.entries.slice(0, limit),
+    modelTotal: rankedModels.total,
+    peakPrompts,
+    promptDays,
+    tokenDays,
+    tokens,
+    totalPrompts,
+  }
+}
+
+/** Blends two theme colours: the palette is flat, so the five-step ramp has to be derived per theme. */
+export function mixColor(from: string, to: string, ratio: number): RGBA {
+  const start = parseColor(from)
+  const end = parseColor(to)
+  // A transparent anchor would fade the whole ramp out; keep the target instead.
+  if (start.a === 0) return end
+  return RGBA.fromValues(
+    start.r + (end.r - start.r) * ratio,
+    start.g + (end.g - start.g) * ratio,
+    start.b + (end.b - start.b) * ratio,
+    1
+  )
+}

package/src/services/usage-history/store.ts

@@ -0,0 +1,174 @@
+import type { AIUsageTool } from '@brimveyn/aimux-config'
+
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import { logDebug } from '../../debug/input-log'
+import { spawnDetachedCommand } from '../../platform/daemon-control'
+
+/**
+ * Long-term AI usage, per local calendar day.
+ *
+ * Claude Code prunes its transcripts after about a month, so this is not a cache
+ * of something re-derivable: once a day is pruned, this file is the only place
+ * its numbers still exist. Hence the refusal to overwrite anything it cannot
+ * fully round-trip.
+ */
+
+export const HISTORY_VERSION = 1
+/** A file that exists but did not parse. Never equal to HISTORY_VERSION, so the save guard refuses it. */
+const UNREADABLE_VERSION = -1
+const ROLLUP_INTERVAL_MS = 20 * 60 * 60 * 1000
+
+export interface UsageTokens {
+  cacheRead: number
+  cacheWrite: number
+  input: number
+  output: number
+  total: number
+}
+
+export interface UsageDay {
+  /** git branch -> tokens. Recent window only; Codex carries no branch. */
+  branches: Record<string, number>
+  /** model id -> tokens. Recent window only. */
+  models: Record<string, number>
+  /** The only field with full-year coverage, and claude-only. */
+  prompts: number
+  tokens: UsageTokens
+}
+
+/** 'YYYY-MM-DD' in the machine's local calendar -> that day's usage. */
+export type UsageDays = Record<string, UsageDay>
+
+/** The key format above — `toISOString()` would shift every evening east of Greenwich by one. */
+export function localDay(date: Date): string {
+  const month = String(date.getMonth() + 1).padStart(2, '0')
+  const day = String(date.getDate()).padStart(2, '0')
+  return `${date.getFullYear()}-${month}-${day}`
+}
+
+export type UsageTools = Partial<Record<AIUsageTool, UsageDays>>
+
+export interface UsageHistoryFile {
+  tools: UsageTools
+  version: number
+}
+
+export function emptyTokens(): UsageTokens {
+  return { cacheRead: 0, cacheWrite: 0, input: 0, output: 0, total: 0 }
+}
+
+export function emptyDay(): UsageDay {
+  return { branches: {}, models: {}, prompts: 0, tokens: emptyTokens() }
+}
+
+/** Resolved per call, not at module scope, so a `HOME` override in tests reaches it. */
+export function usageHistoryPath(): string {
+  const home = process.env.HOME ?? homedir()
+  return join(home, '.config', 'aimux', 'usage-history.json')
+}
+
+export function readUsageHistory(): UsageHistoryFile {
+  let raw: string
+  try {
+    raw = readFileSync(usageHistoryPath(), 'utf8')
+  } catch {
+    return { tools: {}, version: HISTORY_VERSION } // no file yet; safe to create
+  }
+
+  try {
+    const file = JSON.parse(raw) as Partial<UsageHistoryFile>
+    if (typeof file.version !== 'number') return { tools: {}, version: UNREADABLE_VERSION }
+    if (typeof file.tools !== 'object' || file.tools === null) {
+      return { tools: {}, version: UNREADABLE_VERSION }
+    }
+    return { tools: file.tools, version: file.version }
+  } catch {
+    return { tools: {}, version: UNREADABLE_VERSION }
+  }
+}
+
+function mergeDay(stored: UsageDay, fresh: UsageDay): UsageDay {
+  // Pruning only removes data, so a smaller fresh total means the stored copy is
+  // the richer one. `>=` rather than `>` is what makes re-running converge.
+  const keepFresh = fresh.tokens.total >= stored.tokens.total
+  // Prompts merge separately: they outlive the transcripts the tokens came from.
+  return {
+    branches: keepFresh ? fresh.branches : stored.branches,
+    models: keepFresh ? fresh.models : stored.models,
+    prompts: Math.max(fresh.prompts, stored.prompts),
+    tokens: keepFresh ? fresh.tokens : stored.tokens,
+  }
+}
+
+/** Replacement per day, never accumulation — adding would double every total per rollup. */
+export function mergeUsageHistory(stored: UsageTools, fresh: UsageTools): UsageTools {
+  const merged: UsageTools = { ...stored }
+
+  for (const [tool, freshDays] of Object.entries(fresh) as [AIUsageTool, UsageDays][]) {
+    const storedDays = stored[tool] ?? {}
+    const days: UsageDays = { ...storedDays }
+    for (const [date, freshDay] of Object.entries(freshDays)) {
+      const storedDay = storedDays[date]
+      days[date] = storedDay === undefined ? freshDay : mergeDay(storedDay, freshDay)
+    }
+    merged[tool] = days
+  }
+
+  return merged
+}
+
+/** False when nothing was written, which leaves the mtime alone so the next launch retries. */
+export function saveUsageHistory(fresh: UsageTools): boolean {
+  const stored = readUsageHistory()
+
+  // A newer aimux owns a shape this build cannot round-trip; an unreadable file
+  // may still hold years this rollup can no longer see. Neither gets written over.
+  if (stored.version !== HISTORY_VERSION) {
+    logDebug('usageHistory.refusedWrite', { version: stored.version })
+    return false
+  }
+
+  const path = usageHistoryPath()
+  const file: UsageHistoryFile = {
+    tools: mergeUsageHistory(stored.tools, fresh),
+    version: HISTORY_VERSION,
+  }
+
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    // pid-suffixed: two launches can roll up at once, and a shared tmp name would
+    // let one truncate the other's half-written file.
+    const tmpPath = `${path}.${process.pid}.tmp`
+    writeFileSync(tmpPath, `${JSON.stringify(file, null, 2)}\n`)
+    renameSync(tmpPath, path)
+    return true
+  } catch (error) {
+    logDebug('usageHistory.writeError', {
+      error: error instanceof Error ? error.message : String(error),
+    })
+    return false
+  }
+}
+
+/**
+ * Detached because the parse is a second of CPU over hundreds of MB of JSONL.
+ * 20h rather than 24h so opening aimux at the same time each morning does not
+ * land exactly on the boundary and skip every other day.
+ */
+export function maybeSpawnUsageRollup(): void {
+  try {
+    if (process.env.AIMUX_NO_USAGE_ROLLUP === '1') return
+    // mtime is the last successful rollup: the file is written on success and
+    // nothing else. Beats parsing an ever-growing JSON on the startup path.
+    const rolledUpAt = statSync(usageHistoryPath(), { throwIfNoEntry: false })?.mtimeMs ?? 0
+    if (Date.now() - rolledUpAt < ROLLUP_INTERVAL_MS) return
+    spawnDetachedCommand('usage-rollup')
+  } catch (error) {
+    logDebug('usageHistory.spawnError', {
+      error: error instanceof Error ? error.message : String(error),
+    })
+  }
+}

package/src/state/reducers/modal-state.ts

@@ -62,6 +62,9 @@ function getCreateWorkspaceBaseOptions(state: AppState, queryOverride?: string):
 function getModalOptionCount(state: AppState): number {
   const { modal } = state
   switch (modal.type) {
+    // Not a list: the two pages of the AI usage modal, Live and History.
+    case 'ai-usage':
+      return 2
     case 'create-project':
       return modal.directoryResults.length
     case 'help':
@@ -537,6 +540,7 @@ export function reduceModalState(state: AppState, action: AppAction): AppState |
         return { ...state, modal: { ...state.modal, selectedIndex: nextIndex } }
       }
       if (
+        state.modal.type !== 'ai-usage' &&
         state.modal.type !== 'new-tab' &&
         state.modal.type !== 'project-picker' &&
         state.modal.type !== 'snippet-picker' &&