docus 5.4.4 → 5.5.1

package/modules/assistant/runtime/components/AssistantPanel.vue

@@ -0,0 +1,329 @@
+<script setup lang="ts">
+import { defineAsyncComponent } from 'vue'
+import type { UIMessage } from 'ai'
+import { Chat } from '@ai-sdk/vue'
+import { DefaultChatTransport } from 'ai'
+import { createReusableTemplate } from '@vueuse/core'
+import { useDocusI18n } from '../../../../app/composables/useDocusI18n'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const components: Record<string, any> = {
+  pre: defineAsyncComponent(() => import('./AssistantPreStream.vue')),
+}
+
+const [DefineChatContent, ReuseChatContent] = createReusableTemplate<{ showExpandButton?: boolean }>()
+
+const { isOpen, isExpanded, isMobile, panelWidth, toggleExpanded, messages, pendingMessage, clearPending, faqQuestions } = useAssistant()
+const config = useRuntimeConfig()
+const toast = useToast()
+const { t } = useDocusI18n()
+const input = ref('')
+
+const displayTitle = computed(() => t('assistant.title'))
+const displayPlaceholder = computed(() => t('assistant.placeholder'))
+
+const chat = new Chat({
+  messages: messages.value,
+  transport: new DefaultChatTransport({
+    api: config.public.assistant.apiPath,
+  }),
+  onError: (error: Error) => {
+    const message = (() => {
+      try {
+        const parsed = JSON.parse(error.message)
+        return parsed?.message || error.message
+      }
+      catch {
+        return error.message
+      }
+    })()
+
+    toast.add({
+      description: message,
+      icon: 'i-lucide-alert-circle',
+      color: 'error',
+      duration: 0,
+    })
+  },
+  onFinish: () => {
+    messages.value = chat.messages
+  },
+})
+
+watch(pendingMessage, (message: string | undefined) => {
+  if (message) {
+    if (messages.value.length === 0 && chat.messages.length > 0) {
+      chat.messages.length = 0
+    }
+    chat.sendMessage({
+      text: message,
+    })
+    clearPending()
+  }
+}, { immediate: true })
+
+watch(messages, (newMessages: UIMessage[]) => {
+  if (newMessages.length === 0 && chat.messages.length > 0) {
+    chat.messages.length = 0
+  }
+}, { deep: true })
+
+const lastMessage = computed(() => chat.messages.at(-1))
+const showThinking = computed(() =>
+  chat.status === 'streaming'
+  && lastMessage.value?.role === 'assistant'
+  && !lastMessage.value?.parts?.some((p: { type: string }) => p.type === 'text'),
+)
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function getMessageToolCalls(message: any) {
+  if (!message?.parts) return []
+  return message.parts
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    .filter((p: any) => p.type === 'data-tool-calls')
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    .flatMap((p: any) => p.data?.tools || [])
+}
+
+function handleSubmit(event?: Event) {
+  event?.preventDefault()
+
+  if (!input.value.trim()) {
+    return
+  }
+
+  chat.sendMessage({
+    text: input.value,
+  })
+
+  input.value = ''
+}
+
+function askQuestion(question: string) {
+  chat.sendMessage({
+    text: question,
+  })
+}
+
+function resetChat() {
+  chat.stop()
+  messages.value = []
+  chat.messages.length = 0
+}
+
+onMounted(() => {
+  if (pendingMessage.value) {
+    chat.sendMessage({
+      text: pendingMessage.value,
+    })
+    clearPending()
+  }
+  else if (chat.lastMessage?.role === 'user') {
+    chat.regenerate()
+  }
+})
+</script>
+
+<template>
+  <DefineChatContent v-slot="{ showExpandButton = true }">
+    <div class="flex h-full flex-col">
+      <div class="flex h-16 shrink-0 items-center justify-between border-b border-default px-4">
+        <span class="font-medium text-highlighted">{{ displayTitle }}</span>
+        <div class="flex items-center gap-1">
+          <UTooltip
+            v-if="showExpandButton"
+            :text="isExpanded ? t('assistant.collapse') : t('assistant.expand')"
+          >
+            <UButton
+              :icon="isExpanded ? 'i-lucide-minimize-2' : 'i-lucide-maximize-2'"
+              color="neutral"
+              variant="ghost"
+              size="sm"
+              class="text-muted hover:text-highlighted"
+              @click="toggleExpanded"
+            />
+          </UTooltip>
+          <UTooltip
+            v-if="chat.messages.length > 0"
+            :text="t('assistant.clearChat')"
+          >
+            <UButton
+              icon="i-lucide-trash-2"
+              color="neutral"
+              variant="ghost"
+              size="sm"
+              class="text-muted hover:text-highlighted"
+              @click="resetChat"
+            />
+          </UTooltip>
+          <UTooltip :text="t('assistant.close')">
+            <UButton
+              icon="i-lucide-x"
+              color="neutral"
+              variant="ghost"
+              size="sm"
+              class="text-muted hover:text-highlighted"
+              @click="isOpen = false"
+            />
+          </UTooltip>
+        </div>
+      </div>
+
+      <div class="min-h-0 flex-1 overflow-y-auto">
+        <UChatMessages
+          v-if="chat.messages.length > 0"
+          :messages="chat.messages"
+          compact
+          :status="chat.status"
+          :user="{ ui: { content: 'text-sm' } }"
+          :ui="{ indicator: '*:bg-accented', root: 'h-auto!' }"
+          class="px-4 py-4"
+        >
+          <template #content="{ message }">
+            <div class="flex flex-col gap-2">
+              <AssistantLoading
+                v-if="message.role === 'assistant' && (getMessageToolCalls(message).length > 0 || (showThinking && message.id === lastMessage?.id))"
+                :tool-calls="getMessageToolCalls(message)"
+                :is-loading="showThinking && message.id === lastMessage?.id"
+              />
+              <template
+                v-for="(part, index) in message.parts"
+                :key="`${message.id}-${part.type}-${index}${'state' in part ? `-${part.state}` : ''}`"
+              >
+                <MDCCached
+                  v-if="part.type === 'text' && part.text"
+                  :value="part.text"
+                  :cache-key="`${message.id}-${index}`"
+                  :components="components"
+                  :parser-options="{ highlight: false }"
+                  class="*:first:mt-0 *:last:mb-0"
+                />
+              </template>
+            </div>
+          </template>
+        </UChatMessages>
+
+        <div
+          v-else
+          class="p-4"
+        >
+          <div
+            v-if="!faqQuestions?.length"
+            class="flex h-full flex-col items-center justify-center py-12 text-center"
+          >
+            <div class="mb-4 flex size-12 items-center justify-center rounded-full bg-primary/10">
+              <UIcon
+                name="i-lucide-message-circle-question"
+                class="size-6 text-primary"
+              />
+            </div>
+            <h3 class="mb-2 text-base font-medium text-highlighted">
+              {{ t('assistant.askMeAnything') }}
+            </h3>
+            <p class="max-w-xs text-sm text-muted">
+              {{ t('assistant.askMeAnythingDescription') }}
+            </p>
+          </div>
+
+          <template v-else>
+            <p class="mb-4 text-sm font-medium text-muted">
+              {{ t('assistant.faq') }}
+            </p>
+
+            <div class="flex flex-col gap-5">
+              <div
+                v-for="category in faqQuestions"
+                :key="category.category"
+                class="flex flex-col gap-1.5"
+              >
+                <h4 class="text-xs font-medium uppercase tracking-wide text-dimmed">
+                  {{ category.category }}
+                </h4>
+                <div class="flex flex-col">
+                  <button
+                    v-for="question in category.items"
+                    :key="question"
+                    class="py-1.5 text-left text-sm text-muted transition-colors hover:text-highlighted"
+                    @click="askQuestion(question)"
+                  >
+                    {{ question }}
+                  </button>
+                </div>
+              </div>
+            </div>
+          </template>
+        </div>
+      </div>
+
+      <div class="w-full shrink-0 p-3">
+        <UChatPrompt
+          v-model="input"
+          :rows="2"
+          :placeholder="displayPlaceholder"
+          maxlength="1000"
+          :ui="{
+            root: 'shadow-none!',
+            body: '*:p-0! *:rounded-none! *:text-base!',
+          }"
+          @submit="handleSubmit"
+        >
+          <template #footer>
+            <div class="flex items-center gap-1 text-xs text-muted">
+              <span>{{ t('assistant.lineBreak') }}</span>
+              <UKbd
+                size="sm"
+                value="shift"
+              />
+              <UKbd
+                size="sm"
+                value="enter"
+              />
+            </div>
+            <UChatPromptSubmit
+              class="ml-auto"
+              size="xs"
+              :status="chat.status"
+              @stop="chat.stop()"
+              @reload="chat.regenerate()"
+            />
+          </template>
+        </UChatPrompt>
+        <div class="mt-1 flex text-xs text-dimmed items-center justify-between">
+          <span>{{ t('assistant.chatCleared') }}</span>
+          <span>
+            {{ input.length }}/1000
+          </span>
+        </div>
+      </div>
+    </div>
+  </DefineChatContent>
+
+  <aside
+    v-if="!isMobile"
+    class="left-auto! fixed top-0 z-50 h-dvh overflow-hidden border-l border-default bg-default/95 backdrop-blur-xl transition-[right,width] duration-200 ease-linear will-change-[right,width]"
+    :style="{
+      width: `${panelWidth}px`,
+      right: isOpen ? '0' : `-${panelWidth}px`,
+    }"
+  >
+    <div
+      class="h-full transition-[width] duration-200 ease-linear"
+      :style="{ width: `${panelWidth}px` }"
+    >
+      <ReuseChatContent :show-expand-button="true" />
+    </div>
+  </aside>
+
+  <USlideover
+    v-else
+    v-model:open="isOpen"
+    side="right"
+    :ui="{
+      content: 'ring-0 bg-default',
+    }"
+  >
+    <template #content>
+      <ReuseChatContent :show-expand-button="false" />
+    </template>
+  </USlideover>
+</template>

package/modules/assistant/runtime/components/AssistantPreStream.vue

@@ -0,0 +1,46 @@
+<script setup lang="ts">
+import { ShikiCachedRenderer } from 'shiki-stream/vue'
+import { useColorMode } from '#imports'
+import { useHighlighter } from '../composables/useHighlighter'
+
+const colorMode = useColorMode()
+const highlighter = await useHighlighter()
+const props = defineProps<{
+  code: string
+  language: string
+  class?: string
+  meta?: string
+}>()
+const trimmedCode = computed(() => {
+  return props.code.trim().replace(/`+$/, '')
+})
+const lang = computed(() => {
+  switch (props.language) {
+    case 'vue':
+      return 'vue'
+    case 'javascript':
+      return 'js'
+    case 'typescript':
+      return 'ts'
+    case 'css':
+      return 'css'
+    default:
+      return props.language
+  }
+})
+const key = computed(() => {
+  return `${lang.value}-${colorMode.value}`
+})
+</script>
+
+<template>
+  <ProsePre v-bind="props">
+    <ShikiCachedRenderer
+      :key="key"
+      :highlighter="highlighter"
+      :code="trimmedCode"
+      :lang="lang"
+      :theme="colorMode.value === 'dark' ? 'material-theme-palenight' : 'material-theme-lighter'"
+    />
+  </ProsePre>
+</template>

package/modules/assistant/runtime/composables/useAssistant.ts

@@ -0,0 +1,107 @@
+import type { UIMessage } from 'ai'
+import { useMediaQuery } from '@vueuse/core'
+import type { FaqCategory, FaqQuestions, LocalizedFaqQuestions } from '../types'
+
+function normalizeFaqQuestions(questions: FaqQuestions): FaqCategory[] {
+  if (!questions || (Array.isArray(questions) && questions.length === 0)) {
+    return []
+  }
+
+  if (typeof questions[0] === 'string') {
+    return [{
+      category: 'Questions',
+      items: questions as string[],
+    }]
+  }
+
+  return questions as FaqCategory[]
+}
+
+const PANEL_WIDTH_COMPACT = 360
+const PANEL_WIDTH_EXPANDED = 520
+
+export function useAssistant() {
+  const config = useRuntimeConfig()
+  const appConfig = useAppConfig()
+  const isEnabled = computed(() => config.public.assistant?.enabled ?? false)
+
+  const isOpen = useState('assistant-open', () => false)
+  const isExpanded = useState('assistant-expanded', () => false)
+  const messages = useState<UIMessage[]>('assistant-messages', () => [])
+  const pendingMessage = useState<string | undefined>('assistant-pending', () => undefined)
+
+  const isMobile = useMediaQuery('(max-width: 767px)')
+  const panelWidth = computed(() => isExpanded.value ? PANEL_WIDTH_EXPANDED : PANEL_WIDTH_COMPACT)
+  const shouldPushContent = computed(() => !isMobile.value && isOpen.value)
+
+  const faqQuestions = computed<FaqCategory[]>(() => {
+    const assistantConfig = appConfig.assistant
+    const faqConfig = assistantConfig?.faqQuestions
+    if (!faqConfig) return []
+
+    // Check if it's a localized object (has locale keys like 'en', 'fr')
+    if (!Array.isArray(faqConfig)) {
+      const localizedConfig = faqConfig as LocalizedFaqQuestions
+      const currentLocale = appConfig.docus?.locale || 'en'
+      const defaultLocale = config.public.i18n?.defaultLocale || 'en'
+
+      // Try current locale, then default locale, then first available
+      const questions = localizedConfig[currentLocale]
+        || localizedConfig[defaultLocale]
+        || Object.values(localizedConfig)[0]
+
+      return normalizeFaqQuestions(questions || [])
+    }
+
+    return normalizeFaqQuestions(faqConfig)
+  })
+
+  function open(initialMessage?: string, clearPrevious = false) {
+    if (clearPrevious) {
+      messages.value = []
+    }
+
+    if (initialMessage) {
+      pendingMessage.value = initialMessage
+    }
+    isOpen.value = true
+  }
+
+  function clearPending() {
+    pendingMessage.value = undefined
+  }
+
+  function close() {
+    isOpen.value = false
+  }
+
+  function toggle() {
+    isOpen.value = !isOpen.value
+  }
+
+  function clearMessages() {
+    messages.value = []
+  }
+
+  function toggleExpanded() {
+    isExpanded.value = !isExpanded.value
+  }
+
+  return {
+    isEnabled,
+    isOpen,
+    isExpanded,
+    isMobile,
+    panelWidth,
+    shouldPushContent,
+    messages,
+    pendingMessage,
+    faqQuestions,
+    open,
+    clearPending,
+    close,
+    toggle,
+    toggleExpanded,
+    clearMessages,
+  }
+}

package/modules/assistant/runtime/composables/useHighlighter.ts

@@ -0,0 +1,34 @@
+import { createHighlighterCore } from '@shikijs/core'
+import type { HighlighterCore } from '@shikijs/core'
+import { createJavaScriptRegexEngine } from '@shikijs/engine-javascript'
+
+let highlighter: HighlighterCore | null = null
+let promise: Promise<HighlighterCore> | null = null
+
+export const useHighlighter = async () => {
+  if (!promise) {
+    promise = createHighlighterCore({
+      langs: [
+        import('@shikijs/langs/vue'),
+        import('@shikijs/langs/javascript'),
+        import('@shikijs/langs/typescript'),
+        import('@shikijs/langs/css'),
+        import('@shikijs/langs/html'),
+        import('@shikijs/langs/json'),
+        import('@shikijs/langs/yaml'),
+        import('@shikijs/langs/markdown'),
+        import('@shikijs/langs/bash'),
+      ],
+      themes: [
+        import('@shikijs/themes/material-theme-palenight'),
+        import('@shikijs/themes/material-theme-lighter'),
+      ],
+      engine: createJavaScriptRegexEngine(),
+    })
+  }
+  if (!highlighter) {
+    highlighter = await promise
+  }
+
+  return highlighter
+}

package/modules/assistant/runtime/server/api/search.ts

@@ -0,0 +1,111 @@
+import { streamText, convertToModelMessages, createUIMessageStream, createUIMessageStreamResponse } from 'ai'
+import type { UIMessageStreamWriter, ToolCallPart, ToolSet } from 'ai'
+import { createMCPClient } from '@ai-sdk/mcp'
+
+const MAX_STEPS = 10
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function stopWhenResponseComplete({ steps }: { steps: any[] }): boolean {
+  const lastStep = steps.at(-1)
+  if (!lastStep) return false
+
+  // Primary condition: stop when model gives a text response without tool calls
+  const hasText = Boolean(lastStep.text && lastStep.text.trim().length > 0)
+  const hasNoToolCalls = !lastStep.toolCalls || lastStep.toolCalls.length === 0
+
+  if (hasText && hasNoToolCalls) return true
+
+  return steps.length >= MAX_STEPS
+}
+
+function getSystemPrompt(siteName: string) {
+  return `You are the documentation assistant for ${siteName}. Help users navigate and understand the project documentation.
+
+**Your identity:**
+- You are an assistant helping users with ${siteName} documentation
+- NEVER use first person ("I", "me", "my") - always refer to the project by name: "${siteName} provides...", "${siteName} supports...", "The project offers..."
+- Be confident and knowledgeable about the project
+- Speak as a helpful guide, not as the documentation itself
+
+**Tool usage (CRITICAL):**
+- You have tools: list-pages (discover pages) and get-page (read a page)
+- If a page title clearly matches the question, read it directly without listing first
+- ALWAYS respond with text after using tools - never end with just tool calls
+
+**Guidelines:**
+- If you can't find something, say "There is no documentation on that yet" or "${siteName} doesn't cover that topic yet"
+- Be concise, helpful, and direct
+- Guide users like a friendly expert would
+
+**FORMATTING RULES (CRITICAL):**
+- NEVER use markdown headings (#, ##, ###, etc.)
+- Use **bold text** for emphasis and section labels
+- Start responses with content directly, never with a heading
+- Use bullet points for lists
+- Keep code examples focused and minimal
+
+**Response style:**
+- Conversational but professional
+- "Here's how you can do that:" instead of "The documentation shows:"
+- "${siteName} supports TypeScript out of the box" instead of "I support TypeScript"
+- Provide actionable guidance, not just information dumps`
+}
+
+export default defineEventHandler(async (event) => {
+  const { messages } = await readBody(event)
+  const config = useRuntimeConfig()
+  const siteConfig = getSiteConfig(event)
+
+  const siteName = siteConfig.name || 'Documentation'
+
+  const mcpServer = config.assistant.mcpServer
+  const isExternalUrl = mcpServer.startsWith('http://') || mcpServer.startsWith('https://')
+  const mcpUrl = isExternalUrl
+    ? mcpServer
+    : import.meta.dev
+      ? `http://localhost:3000${mcpServer}`
+      : `${getRequestURL(event).origin}${mcpServer}`
+
+  const httpClient = await createMCPClient({
+    transport: { type: 'http', url: mcpUrl },
+  })
+  const mcpTools = await httpClient.tools()
+
+  const stream = createUIMessageStream({
+    execute: async ({ writer }: { writer: UIMessageStreamWriter }) => {
+      const modelMessages = await convertToModelMessages(messages)
+      const result = streamText({
+        model: config.assistant.model,
+        maxOutputTokens: 4000,
+        maxRetries: 2,
+        stopWhen: stopWhenResponseComplete,
+        system: getSystemPrompt(siteName),
+        messages: modelMessages,
+        tools: mcpTools as ToolSet,
+        onStepFinish: ({ toolCalls }: { toolCalls: ToolCallPart[] }) => {
+          if (toolCalls.length === 0) return
+          writer.write({
+            id: toolCalls[0]?.toolCallId,
+            type: 'data-tool-calls',
+            data: {
+              tools: toolCalls.map((tc: ToolCallPart) => {
+                const args = 'args' in tc ? tc.args : 'input' in tc ? tc.input : {}
+                return {
+                  toolName: tc.toolName,
+                  toolCallId: tc.toolCallId,
+                  args,
+                }
+              }),
+            },
+          })
+        },
+      })
+      writer.merge(result.toUIMessageStream())
+    },
+    onFinish: async () => {
+      await httpClient.close()
+    },
+  })
+
+  return createUIMessageStreamResponse({ stream })
+})

package/modules/assistant/runtime/types.ts

@@ -0,0 +1,7 @@
+export interface FaqCategory {
+  category: string
+  items: string[]
+}
+
+export type FaqQuestions = string[] | FaqCategory[]
+export type LocalizedFaqQuestions = Record<string, FaqQuestions>

package/modules/config.ts

@@ -1,10 +1,12 @@
-import { createResolver, defineNuxtModule } from '@nuxt/kit'
+import { createResolver, defineNuxtModule, logger } from '@nuxt/kit'
 import { defu } from 'defu'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { inferSiteURL, getPackageJsonMetadata } from '../utils/meta'
 import { getGitBranch, getGitEnv, getLocalGitInfo } from '../utils/git'
 
+const log = logger.withTag('Docus')
+
 export default defineNuxtModule({
   meta: {
     name: 'config',
@@ -14,7 +16,7 @@ export default defineNuxtModule({
     const url = inferSiteURL()
     const meta = await getPackageJsonMetadata(dir)
     const gitInfo = await getLocalGitInfo(dir) || getGitEnv()
-    const siteName = nuxt.options?.site?.name || meta.name || gitInfo?.name || ''
+    const siteName = (typeof nuxt.options.site === 'object' && nuxt.options.site?.name) || meta.name || gitInfo?.name || ''
 
     nuxt.options.llms = defu(nuxt.options.llms, {
       domain: url,
@@ -68,11 +70,11 @@ export default defineNuxtModule({
         const hasContentFolder = existsSync(contentPath)
 
         if (!hasLocaleFile) {
-          console.warn(`[Docus] Locale file not found: ${localeCode}.json - skipping locale "${localeCode}"`)
+          log.warn(`Locale file not found: ${localeCode}.json - skipping locale "${localeCode}"`)
         }
 
         if (!hasContentFolder) {
-          console.warn(`[Docus] Content folder not found: content/${localeCode}/ - skipping locale "${localeCode}"`)
+          log.warn(`Content folder not found: content/${localeCode}/ - skipping locale "${localeCode}"`)
         }
 
         return hasLocaleFile && hasContentFolder

package/modules/css.ts

@@ -14,6 +14,7 @@ export default defineNuxtModule({
     const uiPath = resolveModulePath('@nuxt/ui', { from: import.meta.url, conditions: ['style'] })
     const tailwindPath = resolveModulePath('tailwindcss', { from: import.meta.url, conditions: ['style'] })
     const layerDir = resolver.resolve('../app')
+    const assistantDir = resolver.resolve('../modules/assistant')
 
     const cssTemplate = addTemplate({
       filename: 'docus.css',
@@ -23,10 +24,13 @@ export default defineNuxtModule({
 
 @source "${contentDir.replace(/\\/g, '/')}/**/*";
 @source "${layerDir.replace(/\\/g, '/')}/**/*";
-@source "../../app.config.ts";`
+@source "../../app.config.ts";
+@source "${assistantDir.replace(/\\/g, '/')}/**/*";`
       },
     })
 
-    nuxt.options.css.unshift(cssTemplate.dst)
+    if (Array.isArray(nuxt.options.css)) {
+      nuxt.options.css.unshift(cssTemplate.dst)
+    }
   },
 })