@alumbwe/anvil 1.0.0

package/src/utils/__tests__/format-timeout.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from 'bun:test'
+
+import { formatTimeout } from '../format-timeout'
+
+describe('formatTimeout', () => {
+  describe('normal values', () => {
+    test('returns seconds for values less than 60', () => {
+      expect(formatTimeout(10)).toBe('10s timeout')
+      expect(formatTimeout(30)).toBe('30s timeout')
+      expect(formatTimeout(45)).toBe('45s timeout')
+    })
+
+    test('returns minutes for values evenly divisible by 60', () => {
+      expect(formatTimeout(60)).toBe('1m timeout')
+      expect(formatTimeout(120)).toBe('2m timeout')
+      expect(formatTimeout(300)).toBe('5m timeout')
+    })
+
+    test('returns hours for values evenly divisible by 3600', () => {
+      expect(formatTimeout(3600)).toBe('1h timeout')
+      expect(formatTimeout(7200)).toBe('2h timeout')
+      expect(formatTimeout(10800)).toBe('3h timeout')
+    })
+
+    test('returns minutes for large values divisible by 60 but not 3600', () => {
+      expect(formatTimeout(5400)).toBe('90m timeout')
+    })
+
+    test('returns seconds for large values not evenly divisible by 60', () => {
+      expect(formatTimeout(3700)).toBe('3700s timeout')
+    })
+
+    test('returns seconds for values >= 60 not evenly divisible by 60', () => {
+      expect(formatTimeout(90)).toBe('90s timeout')
+      expect(formatTimeout(150)).toBe('150s timeout')
+    })
+
+    test('returns "0s timeout" for 0', () => {
+      expect(formatTimeout(0)).toBe('0s timeout')
+    })
+  })
+
+  describe('negative values', () => {
+    test('returns "no timeout" for -1', () => {
+      expect(formatTimeout(-1)).toBe('no timeout')
+    })
+
+    test('returns "no timeout" for other negative values', () => {
+      expect(formatTimeout(-5)).toBe('no timeout')
+      expect(formatTimeout(-100)).toBe('no timeout')
+      expect(formatTimeout(-0.5)).toBe('no timeout')
+    })
+  })
+
+  describe('non-finite values', () => {
+    test('returns "no timeout" for NaN', () => {
+      expect(formatTimeout(NaN)).toBe('no timeout')
+    })
+
+    test('returns "no timeout" for Infinity', () => {
+      expect(formatTimeout(Infinity)).toBe('no timeout')
+    })
+
+    test('returns "no timeout" for -Infinity', () => {
+      expect(formatTimeout(-Infinity)).toBe('no timeout')
+    })
+  })
+
+  describe('floating point values', () => {
+    test('rounds floating point values to nearest integer', () => {
+      expect(formatTimeout(30.4)).toBe('30s timeout')
+      expect(formatTimeout(30.5)).toBe('31s timeout')
+      expect(formatTimeout(30.9)).toBe('31s timeout')
+    })
+
+    test('rounds floating point values for minute display', () => {
+      expect(formatTimeout(59.5)).toBe('1m timeout')
+      expect(formatTimeout(60.4)).toBe('1m timeout')
+      expect(formatTimeout(119.6)).toBe('2m timeout')
+    })
+
+    test('handles floating point values that round to non-minute values', () => {
+      expect(formatTimeout(60.6)).toBe('61s timeout')
+      expect(formatTimeout(89.5)).toBe('90s timeout')
+    })
+  })
+})

package/src/utils/__tests__/freebuff-instance-owner.test.ts

@@ -0,0 +1,69 @@
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+
+import { ensureCliTestEnv } from '../../__tests__/test-utils'
+
+const OWNER_FILE = 'freebuff-instance-owner.json'
+
+ensureCliTestEnv()
+
+const { getConfigDir } = await import('../auth')
+const {
+  isFreebuffInstanceOwnedByDeadLocalProcess,
+  recordFreebuffInstanceOwner,
+} = await import('../freebuff-instance-owner')
+
+describe('freebuff instance owner', () => {
+  let originalHome: string | undefined
+  let tempHome: string
+
+  const ownerPath = () => path.join(getConfigDir(), OWNER_FILE)
+
+  beforeEach(() => {
+    originalHome = process.env.HOME
+    tempHome = fs.mkdtempSync(path.join(os.tmpdir(), 'freebuff-owner-'))
+    process.env.HOME = tempHome
+  })
+
+  afterEach(() => {
+    if (originalHome === undefined) {
+      delete process.env.HOME
+    } else {
+      process.env.HOME = originalHome
+    }
+    fs.rmSync(tempHome, { recursive: true, force: true })
+  })
+
+  test('does not classify the current process as dead', () => {
+    recordFreebuffInstanceOwner('inst-current')
+
+    expect(
+      isFreebuffInstanceOwnedByDeadLocalProcess('inst-current'),
+    ).toBe(false)
+  })
+
+  test('classifies a matching owner with a dead pid as dead', () => {
+    fs.mkdirSync(getConfigDir(), { recursive: true })
+    fs.writeFileSync(
+      ownerPath(),
+      JSON.stringify({ instanceId: 'inst-dead', pid: 2_147_483_647 }),
+    )
+
+    expect(isFreebuffInstanceOwnedByDeadLocalProcess('inst-dead')).toBe(true)
+  })
+
+  test('ignores a dead pid for a different instance id', () => {
+    fs.mkdirSync(getConfigDir(), { recursive: true })
+    fs.writeFileSync(
+      ownerPath(),
+      JSON.stringify({ instanceId: 'inst-other', pid: 2_147_483_647 }),
+    )
+
+    expect(
+      isFreebuffInstanceOwnedByDeadLocalProcess('inst-current'),
+    ).toBe(false)
+  })
+})

package/src/utils/__tests__/freebuff-model-navigation.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, test } from 'bun:test'
+
+import {
+  freebuffModelNavigationDirectionForKey,
+  nextFreebuffModelId,
+} from '../freebuff-model-navigation'
+
+describe('nextFreebuffModelId', () => {
+  test('moves to the next model when moving forward', () => {
+    const modelIds = ['glm', 'minimax']
+
+    expect(
+      nextFreebuffModelId({
+        modelIds,
+        focusedId: 'minimax',
+        direction: 'forward',
+      }),
+    ).toBe('glm')
+  })
+
+  test('moves to the previous model when moving backward', () => {
+    const modelIds = ['glm', 'minimax']
+
+    expect(
+      nextFreebuffModelId({
+        modelIds,
+        focusedId: 'minimax',
+        direction: 'backward',
+      }),
+    ).toBe('glm')
+  })
+
+  test('wraps through every model regardless of selectability', () => {
+    const modelIds = ['glm', 'minimax', 'other']
+
+    expect(
+      nextFreebuffModelId({
+        modelIds,
+        focusedId: 'minimax',
+        direction: 'forward',
+      }),
+    ).toBe('other')
+  })
+
+  test('returns null when no model exists', () => {
+    expect(
+      nextFreebuffModelId({
+        modelIds: [],
+        focusedId: 'glm',
+        direction: 'forward',
+      }),
+    ).toBeNull()
+  })
+})
+
+describe('freebuffModelNavigationDirectionForKey', () => {
+  test('maps arrow keys to model navigation directions', () => {
+    expect(freebuffModelNavigationDirectionForKey({ name: 'down' })).toBe(
+      'forward',
+    )
+    expect(freebuffModelNavigationDirectionForKey({ name: 'right' })).toBe(
+      'forward',
+    )
+    expect(freebuffModelNavigationDirectionForKey({ name: 'up' })).toBe(
+      'backward',
+    )
+    expect(freebuffModelNavigationDirectionForKey({ name: 'left' })).toBe(
+      'backward',
+    )
+  })
+
+  test('maps tab and shift-tab to model navigation directions', () => {
+    expect(freebuffModelNavigationDirectionForKey({ name: 'tab' })).toBe(
+      'forward',
+    )
+    expect(
+      freebuffModelNavigationDirectionForKey({ name: 'tab', shift: true }),
+    ).toBe('backward')
+  })
+
+  test('maps terminal tab sequences to model navigation directions', () => {
+    expect(freebuffModelNavigationDirectionForKey({ sequence: '\t' })).toBe(
+      'forward',
+    )
+    expect(
+      freebuffModelNavigationDirectionForKey({ sequence: '\x1b[9u' }),
+    ).toBe('forward')
+    expect(
+      freebuffModelNavigationDirectionForKey({ sequence: '\x1b[Z' }),
+    ).toBe('backward')
+    expect(
+      freebuffModelNavigationDirectionForKey({ sequence: '\x1b[9;2u' }),
+    ).toBe('backward')
+    expect(
+      freebuffModelNavigationDirectionForKey({ sequence: '\x1b[27;2;9~' }),
+    ).toBe('backward')
+  })
+
+  test('ignores non-navigation keys', () => {
+    expect(freebuffModelNavigationDirectionForKey({ name: 'enter' })).toBeNull()
+  })
+})

package/src/utils/__tests__/freebuff-premium-reset.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from 'bun:test'
+
+import {
+  formatFreebuffPremiumResetCountdown,
+  getFreebuffPremiumResetAt,
+} from '../freebuff-premium-reset'
+
+describe('freebuff premium reset helpers', () => {
+  test('uses server resetAt when it is in the future', () => {
+    const nowMs = Date.parse('2026-05-11T20:00:00.000Z')
+    const resetAt = getFreebuffPremiumResetAt({
+      nowMs,
+      rateLimitsByModel: {
+        'test/model': {
+          model: 'test/model',
+          limit: 5,
+          period: 'pacific_day',
+          resetTimeZone: 'America/Los_Angeles',
+          resetAt: '2026-05-12T07:00:00.000Z',
+          windowHours: 24,
+          recentCount: 2,
+        },
+      },
+    })
+
+    expect(resetAt.toISOString()).toBe('2026-05-12T07:00:00.000Z')
+  })
+
+  test('falls back to next midnight Pacific when resetAt is absent', () => {
+    const resetAt = getFreebuffPremiumResetAt({
+      nowMs: Date.parse('2026-05-11T20:00:00.000Z'),
+    })
+
+    expect(resetAt.toISOString()).toBe('2026-05-12T07:00:00.000Z')
+  })
+
+  test('keeps expired server resetAt instead of rolling stale quota forward', () => {
+    const nowMs = Date.parse('2026-05-12T07:05:00.000Z')
+    const resetAt = getFreebuffPremiumResetAt({
+      nowMs,
+      rateLimitsByModel: {
+        'test/model': {
+          model: 'test/model',
+          limit: 5,
+          period: 'pacific_day',
+          resetTimeZone: 'America/Los_Angeles',
+          resetAt: '2026-05-12T07:00:00.000Z',
+          windowHours: 24,
+          recentCount: 5,
+        },
+      },
+    })
+
+    expect(resetAt.toISOString()).toBe('2026-05-12T07:00:00.000Z')
+    expect(formatFreebuffPremiumResetCountdown(resetAt, nowMs)).toBe('now')
+  })
+
+  test('handles Pacific daylight saving time boundaries', () => {
+    const resetAt = getFreebuffPremiumResetAt({
+      nowMs: Date.parse('2026-01-15T20:00:00.000Z'),
+    })
+
+    expect(resetAt.toISOString()).toBe('2026-01-16T08:00:00.000Z')
+  })
+
+  test('formats hours and minutes left', () => {
+    const nowMs = Date.parse('2026-05-11T20:00:00.000Z')
+    const resetAt = new Date('2026-05-12T07:30:00.000Z')
+
+    expect(formatFreebuffPremiumResetCountdown(resetAt, nowMs)).toBe('11h 30m')
+  })
+
+  test('formats sub-hour reset countdowns', () => {
+    const nowMs = Date.parse('2026-05-12T06:30:00.000Z')
+    const resetAt = new Date('2026-05-12T07:00:00.000Z')
+
+    expect(formatFreebuffPremiumResetCountdown(resetAt, nowMs)).toBe('30m')
+  })
+})

package/src/utils/__tests__/freebuff-referral-cache.test.ts

@@ -0,0 +1,116 @@
+import { beforeEach, describe, expect, test } from 'bun:test'
+
+import {
+  clearReferralCache,
+  getCachedReferral,
+  rememberReferral,
+} from '../freebuff-referral-cache'
+
+import type { FreebuffReferralInfo } from '@anvil/common/types/freebuff-session'
+import type { FreebuffSessionResponse } from '../../types/freebuff-session'
+
+const referral: FreebuffReferralInfo = {
+  code: 'ABC123',
+  referrerName: null,
+  qualifiedCount: 2,
+  weeklySessionsRemaining: 1,
+  resetAt: '2026-07-01T00:00:00.000Z',
+  githubLinked: true,
+}
+
+const landingWithReferral = {
+  status: 'none',
+  accessTier: 'full',
+  referral,
+} satisfies FreebuffSessionResponse
+
+const activeWithoutReferral = {
+  status: 'active',
+  accessTier: 'full',
+  model: 'minimax/minimax-m3',
+  instanceId: 'i-1',
+  admittedAt: '2026-07-01T00:00:00.000Z',
+  expiresAt: '2026-07-01T01:00:00.000Z',
+  remainingMs: 3_600_000,
+} satisfies FreebuffSessionResponse
+
+describe('freebuff referral cache', () => {
+  beforeEach(() => {
+    clearReferralCache()
+  })
+
+  test('starts empty', () => {
+    expect(getCachedReferral('full')).toBeUndefined()
+  })
+
+  test('remembers a referral block from a landing response', () => {
+    rememberReferral(landingWithReferral)
+    expect(getCachedReferral('full')).toEqual(referral)
+  })
+
+  test('keeps the last referral across a join → active round-trip', () => {
+    // Simulates: land on picker (referral present) → join a model (server drops
+    // referral from queued/active payloads). The cache must survive so
+    // returning to the picker can still render the GLM banner.
+    rememberReferral(landingWithReferral)
+    rememberReferral(activeWithoutReferral)
+    expect(getCachedReferral('full')).toEqual(referral)
+  })
+
+  test('ignores responses without a referral block', () => {
+    rememberReferral(activeWithoutReferral)
+    expect(getCachedReferral('full')).toBeUndefined()
+  })
+
+  test('an authoritative landing response clears stale referral metadata', () => {
+    rememberReferral(landingWithReferral)
+    rememberReferral({
+      status: 'none',
+      accessTier: 'full',
+    })
+    expect(getCachedReferral('full')).toBeUndefined()
+  })
+
+  test('ignores null sessions', () => {
+    rememberReferral(landingWithReferral)
+    rememberReferral(null)
+    expect(getCachedReferral('full')).toEqual(referral)
+  })
+
+  test('does not reuse referral metadata across access tiers', () => {
+    rememberReferral(landingWithReferral)
+    expect(getCachedReferral('limited')).toBeUndefined()
+  })
+
+  test('retains independent referral metadata for both tiers', () => {
+    const limitedReferral: FreebuffReferralInfo = {
+      code: referral.code,
+      referrerName: referral.referrerName,
+      qualifiedCount: 3,
+      githubLinked: referral.githubLinked,
+    }
+    rememberReferral(landingWithReferral)
+    rememberReferral({
+      status: 'none',
+      accessTier: 'limited',
+      referral: limitedReferral,
+    })
+
+    expect(getCachedReferral('full')).toEqual(referral)
+    expect(getCachedReferral('limited')).toEqual(limitedReferral)
+  })
+
+  test('does not cache referral metadata without an access tier', () => {
+    rememberReferral({
+      status: 'none',
+      referral,
+    })
+    expect(getCachedReferral('full')).toBeUndefined()
+  })
+
+  test('clears all account-scoped metadata on session-owner unmount', () => {
+    rememberReferral(landingWithReferral)
+    clearReferralCache()
+    expect(getCachedReferral('full')).toBeUndefined()
+  })
+})

package/src/utils/__tests__/freebuff-session-api.test.ts

@@ -0,0 +1,215 @@
+import { afterEach, expect, spyOn, test } from 'bun:test'
+import {
+  FREEBUFF_GLM_V52_MODEL_ID,
+  resolveFreebuffModelForAccessTier,
+} from '@anvil/common/constants/freebuff-models'
+
+import {
+  callFreebuffSession,
+  classifyFreebuffSessionRequestFailure,
+  FreebuffSessionRequestError,
+  mergeCompactActiveSession,
+} from '../freebuff-session-api'
+
+let fetchSpy: ReturnType<typeof spyOn> | undefined
+
+afterEach(() => {
+  fetchSpy?.mockRestore()
+  fetchSpy = undefined
+})
+
+test('full-tier referral GLM reaches the session POST header unchanged', async () => {
+  fetchSpy = spyOn(globalThis, 'fetch').mockResolvedValue(
+    new Response(JSON.stringify({ status: 'none' }), {
+      headers: { 'content-type': 'application/json' },
+    }),
+  )
+  const resolved = resolveFreebuffModelForAccessTier(
+    FREEBUFF_GLM_V52_MODEL_ID,
+    'full',
+  )
+
+  await callFreebuffSession('POST', 'test-token', { model: resolved })
+
+  expect(fetchSpy).toHaveBeenCalledTimes(1)
+  const [, init] = fetchSpy.mock.calls[0]!
+  expect(new Headers(init?.headers).get('x-freebuff-model')).toBe(
+    FREEBUFF_GLM_V52_MODEL_ID,
+  )
+})
+
+test('compact GET sends the compact-session header', async () => {
+  fetchSpy = spyOn(globalThis, 'fetch').mockResolvedValue(
+    Response.json({ status: 'active', model: 'model', instanceId: 'i1' }),
+  )
+
+  await callFreebuffSession('GET', 'test-token', {
+    instanceId: 'i1',
+    compact: true,
+  })
+
+  const [, init] = fetchSpy.mock.calls[0]!
+  expect(new Headers(init?.headers).get('x-freebuff-compact-session')).toBe('1')
+})
+
+test('compact active state retains the admission quota snapshot', () => {
+  const rateLimit = {
+    model: 'model',
+    limit: 5,
+    period: 'pacific_day' as const,
+    resetTimeZone: 'America/Los_Angeles' as const,
+    resetAt: '2026-08-06T07:00:00.000Z',
+    windowHours: 1,
+    recentCount: 2,
+    entitlementBreakdown: { base: 5, referral: 0, streak: 0 },
+  }
+  const merged = mergeCompactActiveSession(
+    {
+      status: 'active',
+      accessTier: 'full',
+      model: 'model',
+      instanceId: 'i1',
+      admittedAt: '2026-08-05T12:00:00.000Z',
+      expiresAt: '2026-08-05T13:00:00.000Z',
+      remainingMs: 1_000,
+      rateLimit,
+    },
+    {
+      status: 'active',
+      accessTier: 'full',
+      model: 'model',
+      instanceId: 'i1',
+      admittedAt: '2026-08-05T12:00:00.000Z',
+      expiresAt: '2026-08-05T13:00:00.000Z',
+      remainingMs: 500,
+    },
+  )
+
+  expect(merged).toMatchObject({ remainingMs: 500, rateLimit })
+})
+
+test('compact state requests a full refresh instead of carrying quota across models', () => {
+  const merged = mergeCompactActiveSession(
+    {
+      status: 'active',
+      accessTier: 'full',
+      model: 'old-model',
+      instanceId: 'i1',
+      admittedAt: '2026-08-05T12:00:00.000Z',
+      expiresAt: '2026-08-05T13:00:00.000Z',
+      remainingMs: 1_000,
+      rateLimit: {
+        model: 'old-model',
+        limit: 5,
+        period: 'pacific_day',
+        resetTimeZone: 'America/Los_Angeles',
+        resetAt: '2026-08-06T07:00:00.000Z',
+        windowHours: 1,
+        recentCount: 2,
+        entitlementBreakdown: { base: 5, referral: 0, streak: 0 },
+      },
+    },
+    {
+      status: 'active',
+      accessTier: 'full',
+      model: 'new-model',
+      instanceId: 'i1',
+      admittedAt: '2026-08-05T12:00:00.000Z',
+      expiresAt: '2026-08-05T13:00:00.000Z',
+      remainingMs: 500,
+    },
+  )
+
+  expect(merged).toBeNull()
+})
+
+test('does not repeat a takeover POST after an ambiguous timeout', () => {
+  const timeout = new DOMException('The operation timed out', 'TimeoutError')
+
+  expect(classifyFreebuffSessionRequestFailure('POST', timeout)).toBe('unknown')
+  expect(classifyFreebuffSessionRequestFailure('GET', timeout)).toBe('retry')
+})
+
+test('retries POST responses that cannot represent a committed takeover', async () => {
+  fetchSpy = spyOn(globalThis, 'fetch').mockResolvedValue(
+    Response.json(
+      {
+        error: 'service_overloaded',
+        message: 'Freebuff session service is busy. Please retry shortly.',
+      },
+      { status: 503, headers: { 'retry-after': '10' } },
+    ),
+  )
+
+  await expect(callFreebuffSession('POST', 'test-token')).rejects.toMatchObject({
+    statusCode: 503,
+    retryAfterMs: 10_000,
+    errorCode: 'service_overloaded',
+  })
+
+  expect(
+    classifyFreebuffSessionRequestFailure(
+      'POST',
+      new FreebuffSessionRequestError(
+        'busy',
+        503,
+        10_000,
+        'service_overloaded',
+      ),
+    ),
+  ).toBe('retry')
+  expect(
+    classifyFreebuffSessionRequestFailure(
+      'POST',
+      new FreebuffSessionRequestError('generic proxy 503', 503, 10_000),
+    ),
+  ).toBe('retry')
+  expect(
+    classifyFreebuffSessionRequestFailure(
+      'POST',
+      new FreebuffSessionRequestError('request timeout', 408, 10_000),
+    ),
+  ).toBe('retry')
+  expect(
+    classifyFreebuffSessionRequestFailure(
+      'POST',
+      new FreebuffSessionRequestError('edge rate limit', 429, 10_000),
+    ),
+  ).toBe('retry')
+})
+
+test('stops on terminal 4xx responses', () => {
+  expect(
+    classifyFreebuffSessionRequestFailure(
+      'POST',
+      new FreebuffSessionRequestError('unauthorized', 401),
+    ),
+  ).toBe('stop')
+  expect(
+    classifyFreebuffSessionRequestFailure(
+      'GET',
+      new FreebuffSessionRequestError('not found', 404),
+    ),
+  ).toBe('stop')
+})
+
+test('marks response loss and server errors after a POST as unknown outcomes', () => {
+  expect(
+    classifyFreebuffSessionRequestFailure(
+      'POST',
+      new TypeError('fetch failed'),
+    ),
+  ).toBe('unknown')
+  expect(
+    classifyFreebuffSessionRequestFailure(
+      'POST',
+      new FreebuffSessionRequestError('internal error', 500),
+    ),
+  ).toBe('unknown')
+  expect(
+    classifyFreebuffSessionRequestFailure(
+      'GET',
+      new FreebuffSessionRequestError('internal error', 500),
+    ),
+  ).toBe('retry')
+})

package/src/utils/__tests__/freebuff-session-display.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from 'bun:test'
+
+import {
+  formatFreebuffSessionCountdown,
+  formatFreebuffSessionRemaining,
+} from '../freebuff-session-display'
+
+describe('freebuff session display formatting', () => {
+  test('formats urgent countdowns', () => {
+    expect(formatFreebuffSessionCountdown(61_000)).toBe('1:01')
+    expect(formatFreebuffSessionRemaining(61_000)).toBe('1:01 left')
+  })
+
+  test('formats minute and hour remaining labels', () => {
+    expect(formatFreebuffSessionRemaining(5 * 60_000)).toBe('5m left')
+    expect(formatFreebuffSessionRemaining(60 * 60_000)).toBe('1h left')
+    expect(formatFreebuffSessionRemaining(90 * 60_000)).toBe('1h 30m left')
+  })
+
+  test('formats expired sessions as expiring', () => {
+    expect(formatFreebuffSessionRemaining(0)).toBe('expiring…')
+  })
+})