@gmickel/gno 0.3.5 → 0.4.0

package/src/serve/CLAUDE.md

@@ -0,0 +1,91 @@
+# Web UI (gno serve)
+
+Local web server for GNO search and document browsing.
+
+## Architecture
+
+Uses same **"Ports without DI"** pattern as CLI/MCP (see root CLAUDE.md):
+- Adapters instantiated directly in `context.ts`
+- Pipeline code receives port interfaces
+- No dependency injection
+
+```
+src/serve/
+├── server.ts          # Bun.serve() entry point
+├── context.ts         # ServerContext with LLM ports
+├── routes/
+│   └── api.ts         # REST API handlers
+└── public/            # React frontend (Bun HTML imports)
+    ├── App.tsx        # Router
+    ├── pages/         # Page components
+    ├── components/    # UI components (ShadCN + AI Elements)
+    └── hooks/         # Custom hooks (useApi, etc.)
+```
+
+## Key Patterns
+
+### Ports (interfaces)
+- `EmbeddingPort` - vector embeddings
+- `GenerationPort` - LLM text generation
+- `RerankPort` - cross-encoder reranking
+- `VectorIndexPort` - vector search
+
+### ServerContext
+Created at startup, holds all LLM ports and capabilities:
+```typescript
+interface ServerContext {
+  store: SqliteAdapter;
+  config: Config;
+  vectorIndex: VectorIndexPort | null;
+  embedPort: EmbeddingPort | null;
+  genPort: GenerationPort | null;
+  rerankPort: RerankPort | null;
+  capabilities: { bm25, vector, hybrid, answer };
+}
+```
+
+### Shared Pipeline Code
+Answer generation uses shared module to stay in sync with CLI:
+- `src/pipeline/answer.ts` - generateGroundedAnswer, processAnswerResult
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/health` | GET | Health check |
+| `/api/status` | GET | Index stats, collections |
+| `/api/capabilities` | GET | Available features |
+| `/api/collections` | GET | List collections |
+| `/api/docs` | GET | List documents |
+| `/api/doc` | GET | Get document content |
+| `/api/search` | POST | BM25 search |
+| `/api/query` | POST | Hybrid search |
+| `/api/ask` | POST | AI answer with citations |
+| `/api/presets` | GET | List model presets |
+| `/api/presets` | POST | Switch preset (hot-reload) |
+| `/api/models/status` | GET | Download progress |
+| `/api/models/pull` | POST | Start model download |
+
+## Frontend
+
+- **Framework**: React (via Bun HTML imports)
+- **Styling**: Tailwind CSS + ShadCN components
+- **AI Elements**: Conversation, Message, Sources, CodeBlock, Loader
+- **Routing**: Simple hash-free SPA routing in App.tsx
+
+## Development
+
+```bash
+# Start dev server with HMR
+bun run src/serve/index.ts
+
+# Or via CLI
+gno serve --port 3000
+```
+
+## Security
+
+- Binds to `127.0.0.1` only (no LAN exposure)
+- CSP headers on all responses
+- CORS protection on POST endpoints
+- No external font/script loading

package/src/serve/bunfig.toml

@@ -0,0 +1,2 @@
+[serve.static]
+plugins = ["bun-plugin-tailwind"]

package/src/serve/context.ts

@@ -0,0 +1,181 @@
+/**
+ * Server context for web UI.
+ * Manages LLM ports and vector index for hybrid search and AI answers.
+ *
+ * @module src/serve/context
+ */
+
+import type { Config } from '../config/types';
+import { LlmAdapter } from '../llm/nodeLlamaCpp/adapter';
+import { getActivePreset } from '../llm/registry';
+import type {
+  DownloadProgress,
+  EmbeddingPort,
+  GenerationPort,
+  ModelType,
+  RerankPort,
+} from '../llm/types';
+import type { SqliteAdapter } from '../store/sqlite/adapter';
+import { createVectorIndexPort, type VectorIndexPort } from '../store/vector';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Download State (in-memory, single user)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface DownloadState {
+  active: boolean;
+  currentType: ModelType | null;
+  progress: DownloadProgress | null;
+  completed: ModelType[];
+  failed: Array<{ type: ModelType; error: string }>;
+  startedAt: number | null;
+}
+
+/** Global download state for polling */
+export const downloadState: DownloadState = {
+  active: false,
+  currentType: null,
+  progress: null,
+  completed: [],
+  failed: [],
+  startedAt: null,
+};
+
+/** Reset download state */
+export function resetDownloadState(): void {
+  downloadState.active = false;
+  downloadState.currentType = null;
+  downloadState.progress = null;
+  downloadState.completed = [];
+  downloadState.failed = [];
+  downloadState.startedAt = null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Server Context
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ServerContext {
+  store: SqliteAdapter;
+  config: Config;
+  vectorIndex: VectorIndexPort | null;
+  embedPort: EmbeddingPort | null;
+  genPort: GenerationPort | null;
+  rerankPort: RerankPort | null;
+  capabilities: {
+    bm25: boolean;
+    vector: boolean;
+    hybrid: boolean;
+    answer: boolean;
+  };
+}
+
+/**
+ * Initialize server context with LLM ports.
+ * Attempts to load models; missing models are logged but don't fail.
+ */
+export async function createServerContext(
+  store: SqliteAdapter,
+  config: Config
+): Promise<ServerContext> {
+  let embedPort: EmbeddingPort | null = null;
+  let genPort: GenerationPort | null = null;
+  let rerankPort: RerankPort | null = null;
+  let vectorIndex: VectorIndexPort | null = null;
+
+  try {
+    const preset = getActivePreset(config);
+    const llm = new LlmAdapter(config);
+
+    // Try to create embedding port
+    const embedResult = await llm.createEmbeddingPort(preset.embed);
+    if (embedResult.ok) {
+      embedPort = embedResult.value;
+      const initResult = await embedPort.init();
+      if (initResult.ok) {
+        // Create vector index
+        const dimensions = embedPort.dimensions();
+        const db = store.getRawDb();
+        const vectorResult = await createVectorIndexPort(db, {
+          model: preset.embed,
+          dimensions,
+        });
+        if (vectorResult.ok) {
+          vectorIndex = vectorResult.value;
+          console.log('Vector search enabled');
+        }
+      }
+    }
+
+    // Try to create generation port
+    const genResult = await llm.createGenerationPort(preset.gen);
+    if (genResult.ok) {
+      genPort = genResult.value;
+      console.log('AI answer generation enabled');
+    }
+
+    // Try to create rerank port
+    const rerankResult = await llm.createRerankPort(preset.rerank);
+    if (rerankResult.ok) {
+      rerankPort = rerankResult.value;
+      console.log('Reranking enabled');
+    }
+  } catch (e) {
+    // Log but don't fail - models are optional
+    console.log(
+      'LLM initialization skipped:',
+      e instanceof Error ? e.message : String(e)
+    );
+  }
+
+  const capabilities = {
+    bm25: true, // Always available
+    vector: vectorIndex?.searchAvailable ?? false,
+    hybrid: (vectorIndex?.searchAvailable ?? false) && embedPort !== null,
+    answer: genPort !== null,
+  };
+
+  return {
+    store,
+    config,
+    vectorIndex,
+    embedPort,
+    genPort,
+    rerankPort,
+    capabilities,
+  };
+}
+
+/**
+ * Dispose server context resources.
+ * Each port is disposed independently to prevent one failure from blocking others.
+ */
+export async function disposeServerContext(ctx: ServerContext): Promise<void> {
+  const ports = [
+    { name: 'embed', port: ctx.embedPort },
+    { name: 'gen', port: ctx.genPort },
+    { name: 'rerank', port: ctx.rerankPort },
+  ];
+
+  for (const { name, port } of ports) {
+    if (port) {
+      try {
+        await port.dispose();
+      } catch (e) {
+        console.error(`Failed to dispose ${name} port:`, e);
+      }
+    }
+  }
+}
+
+/**
+ * Reload server context with potentially new config.
+ * Disposes existing ports and recreates them.
+ */
+export async function reloadServerContext(
+  ctx: ServerContext,
+  newConfig?: Config
+): Promise<ServerContext> {
+  await disposeServerContext(ctx);
+  return createServerContext(ctx.store, newConfig ?? ctx.config);
+}

package/src/serve/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Serve module exports.
+ *
+ * @module src/serve
+ */
+
+export { type ServeOptions, type ServeResult, startServer } from './server';

package/src/serve/public/app.tsx

@@ -0,0 +1,56 @@
+import { useEffect, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import Ask from './pages/Ask';
+import Browse from './pages/Browse';
+import Dashboard from './pages/Dashboard';
+import DocView from './pages/DocView';
+import Search from './pages/Search';
+import './globals.css';
+
+type Route = '/' | '/search' | '/browse' | '/doc' | '/ask';
+type Navigate = (to: string | number) => void;
+
+const routes: Record<Route, React.ComponentType<{ navigate: Navigate }>> = {
+  '/': Dashboard,
+  '/search': Search,
+  '/browse': Browse,
+  '/doc': DocView,
+  '/ask': Ask,
+};
+
+function App() {
+  // Track full location (pathname + search) for proper query param handling
+  const [location, setLocation] = useState<string>(
+    window.location.pathname + window.location.search
+  );
+
+  useEffect(() => {
+    const handlePopState = () =>
+      setLocation(window.location.pathname + window.location.search);
+    window.addEventListener('popstate', handlePopState);
+    return () => window.removeEventListener('popstate', handlePopState);
+  }, []);
+
+  const navigate = (to: string | number) => {
+    if (typeof to === 'number') {
+      // Handle history.go(-1) style navigation
+      window.history.go(to);
+      return;
+    }
+    window.history.pushState({}, '', to);
+    setLocation(to);
+  };
+
+  // Extract base path for routing (ignore query params)
+  const basePath = location.split('?')[0] as Route;
+  const Page = routes[basePath] || Dashboard;
+
+  return <Page navigate={navigate} />;
+}
+
+const rootElement = document.getElementById('root');
+if (!rootElement) {
+  throw new Error('Root element not found');
+}
+const root = createRoot(rootElement);
+root.render(<App />);

package/src/serve/public/components/ai-elements/code-block.tsx

@@ -0,0 +1,176 @@
+import { CheckIcon, CopyIcon } from 'lucide-react';
+import {
+  type ComponentProps,
+  createContext,
+  type HTMLAttributes,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
+import { type BundledLanguage, codeToHtml, type ShikiTransformer } from 'shiki';
+import { cn } from '../../lib/utils';
+import { Button } from '../ui/button';
+
+type CodeBlockProps = HTMLAttributes<HTMLDivElement> & {
+  code: string;
+  language: BundledLanguage;
+  showLineNumbers?: boolean;
+};
+
+interface CodeBlockContextType {
+  code: string;
+}
+
+const CodeBlockContext = createContext<CodeBlockContextType>({
+  code: '',
+});
+
+const lineNumberTransformer: ShikiTransformer = {
+  name: 'line-numbers',
+  line(node, line) {
+    node.children.unshift({
+      type: 'element',
+      tagName: 'span',
+      properties: {
+        className: [
+          'inline-block',
+          'min-w-10',
+          'mr-4',
+          'text-right',
+          'select-none',
+          'text-muted-foreground',
+        ],
+      },
+      children: [{ type: 'text', value: String(line) }],
+    });
+  },
+};
+
+export async function highlightCode(
+  code: string,
+  language: BundledLanguage,
+  showLineNumbers = false
+) {
+  const transformers: ShikiTransformer[] = showLineNumbers
+    ? [lineNumberTransformer]
+    : [];
+
+  return await Promise.all([
+    codeToHtml(code, {
+      lang: language,
+      theme: 'one-light',
+      transformers,
+    }),
+    codeToHtml(code, {
+      lang: language,
+      theme: 'one-dark-pro',
+      transformers,
+    }),
+  ]);
+}
+
+export const CodeBlock = ({
+  code,
+  language,
+  showLineNumbers = false,
+  className,
+  children,
+  ...props
+}: CodeBlockProps) => {
+  const [html, setHtml] = useState<string>('');
+  const [darkHtml, setDarkHtml] = useState<string>('');
+  const mounted = useRef(false);
+
+  useEffect(() => {
+    highlightCode(code, language, showLineNumbers).then(([light, dark]) => {
+      if (!mounted.current) {
+        setHtml(light);
+        setDarkHtml(dark);
+        mounted.current = true;
+      }
+    });
+
+    return () => {
+      mounted.current = false;
+    };
+  }, [code, language, showLineNumbers]);
+
+  return (
+    <CodeBlockContext.Provider value={{ code }}>
+      <div
+        className={cn(
+          'group relative w-full overflow-hidden rounded-md border bg-background text-foreground',
+          className
+        )}
+        {...props}
+      >
+        <div className="relative">
+          <div
+            className="overflow-auto dark:hidden [&>pre]:m-0 [&>pre]:bg-background! [&>pre]:p-4 [&>pre]:text-foreground! [&>pre]:text-sm [&_code]:font-mono [&_code]:text-sm"
+            // biome-ignore lint/security/noDangerouslySetInnerHtml: "this is needed."
+            dangerouslySetInnerHTML={{ __html: html }}
+          />
+          <div
+            className="hidden overflow-auto dark:block [&>pre]:m-0 [&>pre]:bg-background! [&>pre]:p-4 [&>pre]:text-foreground! [&>pre]:text-sm [&_code]:font-mono [&_code]:text-sm"
+            // biome-ignore lint/security/noDangerouslySetInnerHtml: "this is needed."
+            dangerouslySetInnerHTML={{ __html: darkHtml }}
+          />
+          {children && (
+            <div className="absolute top-2 right-2 flex items-center gap-2">
+              {children}
+            </div>
+          )}
+        </div>
+      </div>
+    </CodeBlockContext.Provider>
+  );
+};
+
+export type CodeBlockCopyButtonProps = ComponentProps<typeof Button> & {
+  onCopy?: () => void;
+  onError?: (error: Error) => void;
+  timeout?: number;
+};
+
+export const CodeBlockCopyButton = ({
+  onCopy,
+  onError,
+  timeout = 2000,
+  children,
+  className,
+  ...props
+}: CodeBlockCopyButtonProps) => {
+  const [isCopied, setIsCopied] = useState(false);
+  const { code } = useContext(CodeBlockContext);
+
+  const copyToClipboard = async () => {
+    if (typeof window === 'undefined' || !navigator?.clipboard?.writeText) {
+      onError?.(new Error('Clipboard API not available'));
+      return;
+    }
+
+    try {
+      await navigator.clipboard.writeText(code);
+      setIsCopied(true);
+      onCopy?.();
+      setTimeout(() => setIsCopied(false), timeout);
+    } catch (error) {
+      onError?.(error as Error);
+    }
+  };
+
+  const Icon = isCopied ? CheckIcon : CopyIcon;
+
+  return (
+    <Button
+      className={cn('shrink-0', className)}
+      onClick={copyToClipboard}
+      size="icon"
+      variant="ghost"
+      {...props}
+    >
+      {children ?? <Icon size={14} />}
+    </Button>
+  );
+};

package/src/serve/public/components/ai-elements/conversation.tsx

@@ -0,0 +1,98 @@
+import { ArrowDownIcon } from 'lucide-react';
+import type { ComponentProps } from 'react';
+import { useCallback } from 'react';
+import { StickToBottom, useStickToBottomContext } from 'use-stick-to-bottom';
+import { cn } from '../../lib/utils';
+import { Button } from '../ui/button';
+
+export type ConversationProps = ComponentProps<typeof StickToBottom>;
+
+export const Conversation = ({ className, ...props }: ConversationProps) => (
+  <StickToBottom
+    className={cn('relative flex-1 overflow-y-hidden', className)}
+    initial="smooth"
+    resize="smooth"
+    role="log"
+    {...props}
+  />
+);
+
+export type ConversationContentProps = ComponentProps<
+  typeof StickToBottom.Content
+>;
+
+export const ConversationContent = ({
+  className,
+  ...props
+}: ConversationContentProps) => (
+  <StickToBottom.Content
+    className={cn('flex flex-col gap-8 p-4', className)}
+    {...props}
+  />
+);
+
+export type ConversationEmptyStateProps = ComponentProps<'div'> & {
+  title?: string;
+  description?: string;
+  icon?: React.ReactNode;
+};
+
+export const ConversationEmptyState = ({
+  className,
+  title = 'No messages yet',
+  description = 'Start a conversation to see messages here',
+  icon,
+  children,
+  ...props
+}: ConversationEmptyStateProps) => (
+  <div
+    className={cn(
+      'flex size-full flex-col items-center justify-center gap-3 p-8 text-center',
+      className
+    )}
+    {...props}
+  >
+    {children ?? (
+      <>
+        {icon && <div className="text-muted-foreground">{icon}</div>}
+        <div className="space-y-1">
+          <h3 className="font-medium text-sm">{title}</h3>
+          {description && (
+            <p className="text-muted-foreground text-sm">{description}</p>
+          )}
+        </div>
+      </>
+    )}
+  </div>
+);
+
+export type ConversationScrollButtonProps = ComponentProps<typeof Button>;
+
+export const ConversationScrollButton = ({
+  className,
+  ...props
+}: ConversationScrollButtonProps) => {
+  const { isAtBottom, scrollToBottom } = useStickToBottomContext();
+
+  const handleScrollToBottom = useCallback(() => {
+    scrollToBottom();
+  }, [scrollToBottom]);
+
+  return (
+    !isAtBottom && (
+      <Button
+        className={cn(
+          'absolute bottom-4 left-[50%] translate-x-[-50%] rounded-full',
+          className
+        )}
+        onClick={handleScrollToBottom}
+        size="icon"
+        type="button"
+        variant="outline"
+        {...props}
+      >
+        <ArrowDownIcon className="size-4" />
+      </Button>
+    )
+  );
+};