feat(cli): add /referral command and refactor command routing

- Create command registry pattern with CommandDefinition type
- Add /referral slash command with amber UI (◎ icon)
- Create referral-banner component to display referral link
- Add use-user-details-query hook for flexible user data fetching
- Refactor router with router-utils for cleaner input parsing
- Add comprehensive router input tests
- Referral codes work with or without / prefix

Author: brandonkachen

cli/src/commands/command-registry.ts

@@ -1,8 +1,9 @@
 import { handleInitializationFlowLocally } from './init'
+import { handleReferralCode } from './referral'
 import { handleUsageCommand } from './usage'
 import { useChatStore } from '../state/chat-store'
 import { useLoginStore } from '../state/login-store'
-import { getSystemMessage } from '../utils/message-history'
+import { getSystemMessage, getUserMessage } from '../utils/message-history'
 
 import type { ChatMessage } from '../types/chat'
 import type { MultilineInputHandle } from '../components/multiline-input'
@@ -70,7 +71,33 @@ export const COMMAND_REGISTRY: CommandDefinition[] = [
     name: 'bash',
     aliases: ['!'],
     handler: (params) => {
-      useChatStore.getState().setBashMode(true)
+      useChatStore.getState().setInputMode('bash')
+      params.saveToHistory(params.inputValue.trim())
+      clearInput(params)
+    },
+  },
+  {
+    name: 'referral',
+    aliases: ['redeem'],
+    handler: async (params, args) => {
+      const trimmedArgs = args.trim()
+      
+      // If user provided a code directly, redeem it immediately
+      if (trimmedArgs) {
+        const code = trimmedArgs.startsWith('ref-') ? trimmedArgs : `ref-${trimmedArgs}`
+        const { postUserMessage } = await handleReferralCode(code)
+        params.setMessages((prev) => [
+          ...prev,
+          getUserMessage(params.inputValue.trim()),
+          ...postUserMessage([]),
+        ])
+        params.saveToHistory(params.inputValue.trim())
+        clearInput(params)
+        return
+      }
+      
+      // Otherwise enter referral mode
+      useChatStore.getState().setInputMode('referral')
       params.saveToHistory(params.inputValue.trim())
       clearInput(params)
     },

cli/src/commands/router.ts

@@ -36,14 +36,14 @@ export async function routeUserPrompt(
     setMessages,
   } = params
 
-  const isBashMode = useChatStore.getState().isBashMode
-  const setBashMode = useChatStore.getState().setBashMode
+  const inputMode = useChatStore.getState().inputMode
+  const setInputMode = useChatStore.getState().setInputMode
 
   const trimmed = inputValue.trim()
   if (!trimmed) return
 
   // Handle bash mode commands
-  if (isBashMode) {
+  if (inputMode === 'bash') {
     const commandWithBang = '!' + trimmed
     const toolCallId = crypto.randomUUID()
     const resultBlock: ContentBlock = {
@@ -90,7 +90,25 @@ export async function routeUserPrompt(
 
     saveToHistory(commandWithBang)
     setInputValue({ text: '', cursorPosition: 0, lastEditDueToNav: false })
-    setBashMode(false)
+    setInputMode('default')
+
+    return
+  }
+
+  // Handle referral mode input
+  if (inputMode === 'referral') {
+    // Normalize the referral code - add ref- prefix if not present
+    const referralCode = trimmed.startsWith('ref-') ? trimmed : `ref-${trimmed}`
+    const { postUserMessage: referralPostMessage } =
+      await handleReferralCode(referralCode)
+    setMessages((prev) => [
+      ...prev,
+      getUserMessage(trimmed),
+      ...referralPostMessage([]),
+    ])
+    saveToHistory(trimmed)
+    setInputValue({ text: '', cursorPosition: 0, lastEditDueToNav: false })
+    setInputMode('default')
 
     return
   }

cli/src/components/referral-banner.tsx

@@ -0,0 +1,74 @@
+import React, { useMemo } from 'react'
+
+import { Button } from './button'
+import { useTerminalDimensions } from '../hooks/use-terminal-dimensions'
+import { useTheme } from '../hooks/use-theme'
+import { useUserDetailsQuery } from '../hooks/use-user-details-query'
+import { useChatStore } from '../state/chat-store'
+import { BORDER_CHARS } from '../utils/ui-constants'
+
+export const ReferralBanner = () => {
+  const { terminalWidth } = useTerminalDimensions()
+  const theme = useTheme()
+  const inputMode = useChatStore((state) => state.inputMode)
+  const setInputMode = useChatStore((state) => state.setInputMode)
+  const isReferralMode = inputMode === 'referral'
+  const [isCloseHovered, setIsCloseHovered] = React.useState(false)
+
+  // Fetch referral link when in referral mode
+  const { data: userDetails, isLoading } = useUserDetailsQuery({
+    fields: ['referral_link'] as const,
+    enabled: isReferralMode,
+  })
+  const referralLink = userDetails?.referral_link ?? null
+
+  // Memoize the banner text
+  const text = useMemo(() => {
+    if (isLoading) return 'Loading your referral link...'
+
+    if (!referralLink) {
+      return 'Your referral link is not available yet'
+    }
+
+    return `Share this link with friends:\n${referralLink}`
+  }, [referralLink, isLoading])
+
+  if (!isReferralMode) return null
+
+  return (
+    <box
+      key={terminalWidth}
+      style={{
+        width: '100%',
+        borderStyle: 'single',
+        borderColor: theme.warning,
+        flexDirection: 'row',
+        justifyContent: 'space-between',
+        paddingLeft: 1,
+        paddingRight: 1,
+        marginTop: 0,
+        marginBottom: 0,
+      }}
+      border={['bottom', 'left', 'right']}
+      customBorderChars={BORDER_CHARS}
+    >
+      <text
+        style={{
+          fg: theme.warning,
+          wrapMode: 'word',
+          flexShrink: 1,
+          marginRight: 3,
+        }}
+      >
+        {text}
+      </text>
+      <Button
+        onClick={() => setInputMode('default')}
+        onMouseOver={() => setIsCloseHovered(true)}
+        onMouseOut={() => setIsCloseHovered(false)}
+      >
+        <text style={{ fg: isCloseHovered ? theme.error : theme.muted }}>x</text>
+      </Button>
+    </box>
+  )
+}

cli/src/data/slash-commands.ts

@@ -67,4 +67,10 @@ export const SLASH_COMMANDS: SlashCommand[] = [
     description: 'Enter bash mode ("!" at beginning enters bash mode)',
     aliases: ['!'],
   },
+  {
+    id: 'referral',
+    label: 'referral',
+    description: 'Redeem a referral code for bonus credits',
+    aliases: ['redeem'],
+  },
 ]

cli/src/hooks/use-user-details-query.ts

@@ -0,0 +1,96 @@
+import { useQuery } from '@tanstack/react-query'
+
+import { getAuthToken } from '../utils/auth'
+import { logger as defaultLogger } from '../utils/logger'
+
+import type { Logger } from '@codebuff/common/types/contracts/logger'
+
+// Valid fields that can be fetched from /api/v1/me
+export type UserField =
+  | 'id'
+  | 'email'
+  | 'discord_id'
+  | 'referral_code'
+  | 'referral_link'
+
+// Query keys for type-safe cache management
+export const userDetailsQueryKeys = {
+  all: ['userDetails'] as const,
+  fields: (fields: readonly UserField[]) =>
+    [...userDetailsQueryKeys.all, ...fields] as const,
+}
+
+export type UserDetails<T extends UserField> = {
+  [K in T]: K extends 'discord_id' | 'referral_code' | 'referral_link'
+    ? string | null
+    : string
+}
+
+interface FetchUserDetailsParams<T extends UserField> {
+  authToken: string
+  fields: readonly T[]
+  logger?: Logger
+}
+
+/**
+ * Fetches specific user details from the /api/v1/me endpoint
+ */
+export async function fetchUserDetails<T extends UserField>({
+  authToken,
+  fields,
+  logger = defaultLogger,
+}: FetchUserDetailsParams<T>): Promise<UserDetails<T> | null> {
+  const appUrl = process.env.NEXT_PUBLIC_CODEBUFF_APP_URL
+  if (!appUrl) {
+    throw new Error('NEXT_PUBLIC_CODEBUFF_APP_URL is not set')
+  }
+
+  const fieldsParam = fields.join(',')
+  const response = await fetch(`${appUrl}/api/v1/me?fields=${fieldsParam}`, {
+    method: 'GET',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${authToken}`,
+    },
+  })
+
+  if (!response.ok) {
+    logger.error(
+      { status: response.status, fields },
+      'Failed to fetch user details from /api/v1/me',
+    )
+    return null
+  }
+
+  const data = (await response.json()) as UserDetails<T>
+  return data
+}
+
+export interface UseUserDetailsQueryDeps<T extends UserField> {
+  fields: readonly T[]
+  logger?: Logger
+  enabled?: boolean
+}
+
+/**
+ * Hook to fetch specific user details
+ */
+export function useUserDetailsQuery<T extends UserField>({
+  fields,
+  logger = defaultLogger,
+  enabled = true,
+}: UseUserDetailsQueryDeps<T>) {
+  const authToken = getAuthToken()
+
+  return useQuery({
+    queryKey: userDetailsQueryKeys.fields(fields),
+    queryFn: () => fetchUserDetails({ authToken: authToken!, fields, logger }),
+    enabled: enabled && !!authToken,
+    staleTime: 5 * 60 * 1000, // 5 minutes
+    gcTime: 30 * 60 * 1000, // 30 minutes
+    retry: false,
+    refetchOnMount: false,
+    refetchOnWindowFocus: false,
+    refetchOnReconnect: false,
+  })
+}