jamdesk 1.0.13 → 1.0.14

package/vendored/hooks/useChat.ts

@@ -0,0 +1,335 @@
+'use client';
+
+import { useState, useRef, useCallback, useEffect } from 'react';
+
+export interface Citation {
+  title: string;
+  slug: string;
+  section?: string;
+}
+
+export interface ChatMessage {
+  id: string;
+  role: 'user' | 'assistant';
+  content: string;
+  citations?: Citation[];
+  clarificationOptions?: string[];
+  /** Set to true after user taps a clarification option — disables buttons on this message. */
+  clarificationSelected?: boolean;
+  isStreaming?: boolean;
+}
+
+function generateId(): string {
+  return typeof crypto !== 'undefined' && crypto.randomUUID
+    ? crypto.randomUUID()
+    : `msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+const STORAGE_KEY = 'jd-chat-messages';
+
+/** Save messages to sessionStorage (best-effort, silently fails during SSR). */
+function saveMessages(messages: ChatMessage[]): void {
+  try {
+    if (messages.length === 0) {
+      sessionStorage.removeItem(STORAGE_KEY);
+    } else {
+      sessionStorage.setItem(STORAGE_KEY, JSON.stringify(messages));
+    }
+  } catch {}
+}
+
+/** Load messages from sessionStorage, clearing any stale streaming flags. */
+function loadMessages(): ChatMessage[] {
+  try {
+    const saved = sessionStorage.getItem(STORAGE_KEY);
+    if (!saved) return [];
+    const parsed: ChatMessage[] = JSON.parse(saved);
+    return parsed.map(m => ({ ...m, isStreaming: false }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Hook for managing chat state and streaming SSE responses.
+ * POSTs to the given endpoint — in production, /_chat is rewritten by middleware
+ * to /api/chat/{projectSlug}. In local dev, the direct API path is used.
+ *
+ * Messages persist in sessionStorage across page navigations within the same tab.
+ */
+export function useChat(endpoint = '/_chat'): {
+  messages: ChatMessage[];
+  sendMessage: (text: string) => Promise<void>;
+  isLoading: boolean;
+  abort: () => void;
+  retry: () => void;
+  clearChat: () => void;
+  error: string | null;
+  markClarificationSelected: (messageId: string) => void;
+} {
+  const [messages, setMessages] = useState<ChatMessage[]>(loadMessages);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const abortControllerRef = useRef<AbortController | null>(null);
+  const isLoadingRef = useRef(false);
+  const lastUserMessageRef = useRef<string | null>(null);
+  const messagesRef = useRef<ChatMessage[]>(messages);
+
+  // Keep messagesRef in sync for use in callbacks without stale closures
+  useEffect(() => {
+    messagesRef.current = messages;
+  }, [messages]);
+
+  // Persist messages to sessionStorage — debounced to avoid thrashing during streaming
+  useEffect(() => {
+    const timer = setTimeout(() => saveMessages(messages), 500);
+    return () => clearTimeout(timer);
+  }, [messages]);
+
+  // Restore lastUserMessageRef from persisted messages on mount
+  useEffect(() => {
+    const lastUser = messagesRef.current.filter(m => m.role === 'user').at(-1);
+    if (lastUser) lastUserMessageRef.current = lastUser.content;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  /** Mark an assistant message as done streaming and reset loading state.
+   *  If the assistant message has no content, remove it to avoid an empty bubble. */
+  const finishLoading = useCallback((assistantId: string): void => {
+    setMessages((prev) => {
+      const msg = prev.find((m) => m.id === assistantId);
+      if (msg && !msg.content) {
+        return prev.filter((m) => m.id !== assistantId);
+      }
+      return prev.map((m) => (m.id === assistantId ? { ...m, isStreaming: false } : m));
+    });
+    setIsLoading(false);
+    isLoadingRef.current = false;
+    abortControllerRef.current = null;
+  }, []);
+
+  const processStream = useCallback(
+    async (response: Response, assistantId: string) => {
+      const reader = response.body!.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+
+      // Batch text chunks — accumulate in ref, flush to state once per animation frame.
+      // This reduces React re-renders from ~100/sec (per SSE chunk) to ~60/sec (per frame).
+      let pendingText = '';
+      let rafId: ReturnType<typeof requestAnimationFrame> | null = null;
+
+      const flushText = () => {
+        if (!pendingText) return;
+        const text = pendingText;
+        pendingText = '';
+        rafId = null;
+        setMessages((prev) =>
+          prev.map((msg) =>
+            msg.id === assistantId
+              ? { ...msg, content: msg.content + text }
+              : msg,
+          ),
+        );
+      };
+
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+
+          buffer += decoder.decode(value, { stream: true });
+          const lines = buffer.split('\n');
+          buffer = lines.pop() || '';
+
+          for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed.startsWith('data: ')) continue;
+
+            let event: { type: string; content?: string; message?: string; sources?: Citation[]; options?: string[] };
+            try {
+              event = JSON.parse(trimmed.slice(6));
+            } catch {
+              continue;
+            }
+
+            switch (event.type) {
+              case 'text':
+                pendingText += event.content || '';
+                if (rafId === null) {
+                  rafId = requestAnimationFrame(flushText);
+                }
+                break;
+
+              case 'citations':
+                setMessages((prev) =>
+                  prev.map((msg) =>
+                    msg.id === assistantId ? { ...msg, citations: event.sources } : msg,
+                  ),
+                );
+                break;
+
+              case 'clarification':
+                setMessages((prev) =>
+                  prev.map((msg) =>
+                    msg.id === assistantId
+                      ? { ...msg, clarificationOptions: event.options as string[] }
+                      : msg,
+                  ),
+                );
+                break;
+
+              case 'done':
+                // finishLoading in `finally` handles cleanup
+                break;
+
+              case 'error':
+                setError(event.message || 'An error occurred');
+                break;
+            }
+          }
+        }
+      } catch (err) {
+        if (!(err instanceof DOMException && err.name === 'AbortError')) {
+          setError('The response was interrupted. Please try again.');
+        }
+      } finally {
+        // Flush any remaining batched text before finishing
+        if (rafId !== null) cancelAnimationFrame(rafId);
+        flushText();
+        // Unified cleanup: removes empty bubbles, marks streaming done, resets loading
+        finishLoading(assistantId);
+      }
+    },
+    [finishLoading],
+  );
+
+  const sendMessage = useCallback(
+    async (text: string) => {
+      const trimmed = text.trim();
+      if (!trimmed || isLoadingRef.current) return;
+
+      setError(null);
+      setIsLoading(true);
+      isLoadingRef.current = true;
+      lastUserMessageRef.current = trimmed;
+
+      const userMessage: ChatMessage = {
+        id: generateId(),
+        role: 'user',
+        content: trimmed,
+      };
+
+      const assistantMessage: ChatMessage = {
+        id: generateId(),
+        role: 'assistant',
+        content: '',
+        isStreaming: true,
+      };
+
+      setMessages((prev) => [
+        // Auto-disable any outstanding clarification buttons when user sends a new message
+        ...prev.map((m) =>
+          m.clarificationOptions && !m.clarificationSelected
+            ? { ...m, clarificationSelected: true }
+            : m,
+        ),
+        userMessage,
+        assistantMessage,
+      ]);
+
+      // Use messagesRef to avoid stale closure — ref always has current state
+      const currentMessages = [...messagesRef.current, userMessage];
+      const history = currentMessages.slice(-10).map((msg) => ({
+        role: msg.role,
+        content: msg.content,
+      }));
+
+      const controller = new AbortController();
+      abortControllerRef.current = controller;
+
+      // When docs are hosted at /docs (subpath proxy), use /docs/_chat so the request
+      // goes through existing proxy paths — no Cloudflare Worker update needed.
+      // Middleware already handles both /_chat and /docs/_chat.
+      const chatUrl = endpoint === '/_chat' && window.location.pathname.startsWith('/docs')
+        ? '/docs/_chat'
+        : endpoint;
+
+      try {
+        const response = await fetch(chatUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ message: trimmed, history }),
+          signal: controller.signal,
+        });
+
+        if (!response.ok) {
+          let errorMessage = 'Something went wrong. Please try again.';
+          if (response.status === 429) {
+            errorMessage = 'Too many requests. Please wait a moment and try again.';
+          } else if (response.status === 503) {
+            errorMessage = 'AI chat is temporarily unavailable. Please try again later.';
+          }
+          setError(errorMessage);
+          finishLoading(assistantMessage.id);
+          return;
+        }
+
+        await processStream(response, assistantMessage.id);
+      } catch (err) {
+        if (!(err instanceof DOMException && err.name === 'AbortError')) {
+          setError('Unable to connect. Check your internet connection and try again.');
+        }
+        finishLoading(assistantMessage.id);
+      }
+    },
+    [endpoint, processStream, finishLoading],
+  );
+
+  const abort = useCallback(() => {
+    if (!isLoadingRef.current) return;
+    abortControllerRef.current?.abort();
+  }, []);
+
+  const retry = useCallback(() => {
+    if (isLoadingRef.current || !lastUserMessageRef.current) return;
+
+    const lastMessage = lastUserMessageRef.current;
+
+    // Remove the last user + assistant message pair before resending
+    setMessages((prev) => {
+      const remaining = prev.slice();
+      if (remaining.at(-1)?.role === 'assistant') remaining.pop();
+      if (remaining.at(-1)?.role === 'user') remaining.pop();
+      return remaining;
+    });
+
+    // Defer to let the state update from setMessages flush first
+    setTimeout(() => sendMessage(lastMessage), 0);
+  }, [sendMessage]);
+
+  const clearChat = useCallback(() => {
+    abort();
+    setMessages([]);
+    setError(null);
+    lastUserMessageRef.current = null;
+  }, [abort]);
+
+  /** Mark a clarification message's buttons as selected (disables them). */
+  const markClarificationSelected = useCallback((messageId: string) => {
+    setMessages((prev) =>
+      prev.map((m) => (m.id === messageId ? { ...m, clarificationSelected: true } : m)),
+    );
+  }, []);
+
+  return {
+    messages,
+    sendMessage,
+    isLoading,
+    abort,
+    retry,
+    clearChat,
+    error,
+    markClarificationSelected,
+  };
+}

package/vendored/hooks/useChatPanel.tsx

@@ -0,0 +1,101 @@
+'use client';
+
+import { createContext, useContext, useState, useEffect, useCallback, type ReactNode } from 'react';
+
+const MIN_WIDTH = 350;
+const MAX_WIDTH = 500;
+const DEFAULT_WIDTH = 350;
+const STORAGE_KEY = 'jd-chat-width';
+
+interface ChatPanelContextValue {
+  isChatOpen: boolean;
+  setIsChatOpen: (open: boolean) => void;
+  chatWidth: number;
+  setChatWidth: (width: number) => void;
+  chatEnabled: boolean;
+  chatEndpoint: string;
+  starterQuestions?: string[];
+}
+
+const ChatPanelContext = createContext<ChatPanelContextValue | null>(null);
+
+interface ChatPanelProviderProps {
+  children: ReactNode;
+  chatEnabled: boolean;
+  chatEndpoint: string;
+  starterQuestions?: string[];
+}
+
+function clampWidth(width: number): number {
+  return Math.min(MAX_WIDTH, Math.max(MIN_WIDTH, width));
+}
+
+export function ChatPanelProvider({ children, chatEnabled, chatEndpoint, starterQuestions }: ChatPanelProviderProps) {
+  const [isChatOpen, setIsChatOpen] = useState(false);
+  const [chatWidth, setChatWidthRaw] = useState(DEFAULT_WIDTH);
+
+  // Load persisted width from localStorage
+  useEffect(() => {
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY);
+      if (stored) {
+        const parsed = Number(stored);
+        if (!Number.isNaN(parsed) && parsed >= MIN_WIDTH && parsed <= MAX_WIDTH) {
+          setChatWidthRaw(parsed);
+        }
+      }
+    } catch {
+      // localStorage unavailable
+    }
+  }, []);
+
+  const setChatWidth = useCallback((width: number) => {
+    const clamped = clampWidth(width);
+    setChatWidthRaw(clamped);
+    try {
+      localStorage.setItem(STORAGE_KEY, String(clamped));
+    } catch {
+      // localStorage unavailable
+    }
+  }, []);
+
+  // Keyboard shortcuts: Cmd+I / Ctrl+I to toggle, Escape to close
+  // Uses capture phase for Escape so it fires before SearchModal's bubble-phase handler
+  useEffect(() => {
+    if (!chatEnabled) return;
+
+    const handler = (e: KeyboardEvent) => {
+      // Cmd+I / Ctrl+I — toggle chat
+      if (e.key === 'i' && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        setIsChatOpen(prev => !prev);
+      }
+      // Escape — close chat (only if chat is open AND search modal isn't open)
+      if (e.key === 'Escape' && isChatOpen) {
+        const searchOpen = document.querySelector('[aria-label="Search documentation"][role="dialog"]');
+        if (searchOpen) return; // Let search modal handle Escape
+        e.preventDefault();
+        e.stopPropagation();
+        setIsChatOpen(false);
+      }
+    };
+    document.addEventListener('keydown', handler, true); // capture phase
+    return () => document.removeEventListener('keydown', handler, true);
+  }, [chatEnabled, isChatOpen]);
+
+  return (
+    <ChatPanelContext.Provider value={{ isChatOpen, setIsChatOpen, chatWidth, setChatWidth, chatEnabled, chatEndpoint, starterQuestions }}>
+      {children}
+    </ChatPanelContext.Provider>
+  );
+}
+
+export function useChatPanel(): ChatPanelContextValue {
+  const context = useContext(ChatPanelContext);
+  if (!context) {
+    throw new Error('useChatPanel must be used within a ChatPanelProvider');
+  }
+  return context;
+}
+
+export { MIN_WIDTH, MAX_WIDTH, DEFAULT_WIDTH };

package/vendored/lib/anthropic-client.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared Anthropic Client
+ *
+ * Provides a singleton Anthropic SDK client for reuse across the chat route
+ * and build-time starter question generation. Reusing a single client allows
+ * HTTP connection pooling across requests on the same Cloud Run instance.
+ */
+import Anthropic from '@anthropic-ai/sdk';
+
+let client: Anthropic | null = null;
+
+/** Get or create the shared Anthropic client. Returns null if API key is not configured. */
+export function getAnthropicClient(): Anthropic | null {
+  if (!process.env.ANTHROPIC_API_KEY) return null;
+  if (!client) {
+    client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+  }
+  return client;
+}

package/vendored/lib/build/extract-tarball.ts

@@ -0,0 +1,150 @@
+/**
+ * Extract a CLI-uploaded tarball from R2 into a local directory.
+ *
+ * Security measures:
+ * - execFileSync (not execSync) to prevent shell injection
+ * - --no-absolute-filenames to prevent path traversal via absolute paths
+ * - Post-extraction symlink validation to prevent symlink escape
+ * - Decompressed size limit (500MB) to prevent decompression bombs
+ * - 60-second timeout on tar extraction
+ */
+
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { GetObjectCommand, DeleteObjectCommand } from '@aws-sdk/client-s3';
+import { getR2S3Client, getR2Config } from '../r2.js';
+import { logger } from '../../shared/logger.js';
+
+const MAX_DECOMPRESSED_SIZE_BYTES = 500 * 1024 * 1024; // 500MB
+
+/**
+ * Download a tarball from R2, extract it to repoDir, and clean up.
+ */
+export async function extractTarball(tarballKey: string, repoDir: string): Promise<void> {
+  if (!tarballKey) throw new Error('tarballKey is required');
+  if (!repoDir) throw new Error('repoDir is required');
+
+  const { bucketName } = getR2Config();
+  const client = getR2S3Client();
+
+  // Download tarball from R2 to a temp file
+  const response = await client.send(new GetObjectCommand({
+    Bucket: bucketName,
+    Key: tarballKey,
+  }));
+
+  if (!response.Body) {
+    throw new Error(`Tarball not found in R2: ${tarballKey}`);
+  }
+
+  // Write to temp file
+  const tmpTarball = path.join(os.tmpdir(), `cli-upload-${Date.now()}.tar.gz`);
+
+  try {
+    const bodyBytes = await response.Body.transformToByteArray();
+    fs.writeFileSync(tmpTarball, bodyBytes);
+
+    // Create target directory
+    fs.mkdirSync(repoDir, { recursive: true });
+
+    // Extract with security flags
+    // GNU tar (Linux/Cloud Run) strips leading '/' by default, so no --absolute-names flag needed.
+    // --no-same-owner/--no-same-permissions prevent privilege escalation.
+    // macOS BSD tar is safe by default (no owner/permission preservation).
+    const isLinux = process.platform === 'linux';
+    const tarArgs = [
+      '-xzf', tmpTarball,
+      '-C', repoDir,
+      ...(isLinux ? ['--no-same-owner', '--no-same-permissions'] : []),
+    ];
+    execFileSync('tar', tarArgs, {
+      timeout: 60000,
+    });
+
+    // Post-extraction security checks
+    validateNoSymlinkEscape(repoDir);
+    validateDecompressedSize(repoDir);
+
+    logger.info('Tarball extracted successfully', {
+      tarballKey,
+      repoDir,
+    });
+  } finally {
+    // Clean up temp file
+    try {
+      if (fs.existsSync(tmpTarball)) {
+        fs.unlinkSync(tmpTarball);
+      }
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+
+  // Delete tarball from R2 (fire-and-forget)
+  client.send(new DeleteObjectCommand({
+    Bucket: bucketName,
+    Key: tarballKey,
+  })).catch((err) => {
+    logger.warn('Failed to delete tarball from R2 (non-fatal)', {
+      tarballKey,
+      error: (err as Error).message,
+    });
+  });
+}
+
+/**
+ * Walk repoDir recursively and verify no symlinks point outside it.
+ */
+function validateNoSymlinkEscape(repoDir: string): void {
+  const realRepoDir = fs.realpathSync(repoDir);
+
+  function walk(dir: string): void {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isSymbolicLink()) {
+        const target = fs.realpathSync(fullPath);
+        if (!target.startsWith(realRepoDir + path.sep) && target !== realRepoDir) {
+          // Remove the offending symlink and throw
+          fs.unlinkSync(fullPath);
+          throw new Error(
+            `Symlink escape detected: ${path.relative(repoDir, fullPath)} -> ${target} (outside ${realRepoDir})`
+          );
+        }
+      } else if (entry.isDirectory()) {
+        walk(fullPath);
+      }
+    }
+  }
+
+  walk(repoDir);
+}
+
+/**
+ * Check total decompressed size doesn't exceed limit.
+ */
+function validateDecompressedSize(repoDir: string): void {
+  let totalSize = 0;
+
+  function walk(dir: string): void {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory() && !entry.isSymbolicLink()) {
+        walk(fullPath);
+      } else if (entry.isFile()) {
+        totalSize += fs.statSync(fullPath).size;
+        if (totalSize > MAX_DECOMPRESSED_SIZE_BYTES) {
+          throw new Error(
+            `Decompressed size exceeds limit: ${Math.round(totalSize / 1024 / 1024)}MB > ${MAX_DECOMPRESSED_SIZE_BYTES / 1024 / 1024}MB`
+          );
+        }
+      }
+    }
+  }
+
+  walk(repoDir);
+}

package/vendored/lib/chat-prompt.ts

@@ -0,0 +1,56 @@
+/**
+ * Chat System Prompt Builder
+ *
+ * Builds the system prompt for Claude Haiku 4.5, incorporating RAG context
+ * from Upstash Vector search results. The prompt instructs Claude to only
+ * answer from provided documentation and cite sources with links.
+ */
+
+export interface ChatContext {
+  pageSlug: string;
+  sectionHeading: string;
+  pageTitle: string;
+  content: string;
+  score: number;
+}
+
+export function buildSystemPrompt(
+  projectName: string,
+  chunks: ChatContext[],
+  baseUrl: string,
+  docsPath: string,
+): string {
+  const context = chunks.map((c, i) =>
+    `[Source ${i + 1}: ${c.pageTitle} > ${c.sectionHeading}](${baseUrl}${docsPath}/${c.pageSlug})\n${c.content}`
+  ).join('\n\n---\n\n');
+
+  return `You are a helpful documentation assistant for ${projectName}.
+Answer questions using ONLY the documentation context below. If the answer is not in the context, say "I don't have information about that in the documentation."
+
+Rules:
+- Be concise and direct
+- Use markdown formatting, including code blocks with language hints when showing code
+- Cite sources by referencing the page title in brackets, e.g. [Getting Started]
+- If unsure, say so rather than guessing
+- Never make up information not in the context
+- DISAMBIGUATION (highest priority): If the context contains multiple distinct features or topics that could match the user's question (e.g., "Post Analytics" vs "Link Analytics" when asked about "analytics"), you MUST ask which one first — even if the user also asked for code examples or details. Your ENTIRE response must follow this EXACT format — nothing else:
+
+<question ending with ?>
+
+1. <option>
+2. <option>
+3. <option>
+
+Rules: question mark required, numbered list required (1. 2. 3.), no descriptions after options, no extra text before or after. Example:
+
+Which type of analytics are you interested in?
+
+1. Post Analytics
+2. Social Analytics
+3. Link Analytics
+- When the context includes API endpoints (e.g. "POST /analytics/post") or technical operations, proactively include a short code example showing the request (HTTP method, endpoint, JSON body) even if the user didn't explicitly ask for one. Technical users expect to see code. If the context has no code-relevant information, skip the example.
+- When constructing code examples from API endpoints in the context, use the endpoint, HTTP method, and any parameters/body fields mentioned. Always note it's a basic example and link to the full API reference page.
+
+Documentation context:
+${context}`;
+}

package/vendored/lib/docs-types.ts

@@ -617,6 +617,16 @@ export interface SearchConfig {
   }>;
 }
 
+/**
+ * AI Chat configuration
+ */
+export interface ChatConfig {
+  /** Enable AI chat assistant (default: false) */
+  enabled?: boolean;
+  /** Starter questions shown in empty state (max 4). Auto-generated by Haiku during builds when omitted. Set to [] to disable. */
+  starterQuestions?: string[];
+}
+
 /**
  * SEO configuration
  */
@@ -725,6 +735,9 @@ export interface DocsConfig {
   // Schema reference
   $schema?: string;
 
+  // Meta fields (set by CLI)
+  projectId?: string;
+
   // Required fields
   theme: ThemeName;
   name: string;
@@ -774,6 +787,7 @@ export interface DocsConfig {
   interaction?: InteractionConfig;
   metadata?: MetadataConfig;
   analytics?: AnalyticsConfig;
+  chat?: ChatConfig;
 
   // Mintlify compatibility fields (normalized at load time)
   modeToggle?: ModeToggleConfig;