handoff-app 2.0.0-8 → 2.0.0

package/drizzle/meta/_journal.json

@@ -50,6 +50,20 @@
       "when": 1788980586467,
       "tag": "0006_add_component_source_format",
       "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "7",
+      "when": 1789827999294,
+      "tag": "0007_add_ai_keys",
+      "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "7",
+      "when": 1790876591116,
+      "tag": "0008_add_source_dir",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-app",
-  "version": "2.0.0-8",
+  "version": "2.0.0",
   "description": "Automated documentation toolchain for building client side documentation from figma",
   "author ": {
     "name": "Convertiv",
@@ -40,6 +40,10 @@
       "types": "./dist/pattern.d.ts",
       "default": "./dist/pattern.js"
     },
+    "./providers": {
+      "types": "./dist/providers.d.ts",
+      "default": "./dist/providers.js"
+    },
     "./package.json": "./package.json",
     "./*": "./*"
   },
@@ -53,6 +57,9 @@
       ],
       "pattern": [
         "./dist/pattern.d.ts"
+      ],
+      "providers": [
+        "./dist/providers.d.ts"
       ]
     }
   },
@@ -60,8 +67,8 @@
     "handoff-app": "./dist/cli.js"
   },
   "engines": {
-    "npm": ">=8.0.0",
-    "node": ">=16.0.0"
+    "npm": ">=10",
+    "node": ">=22"
   },
   "scripts": {
     "start": "node ./dist/cli.js start",
@@ -82,9 +89,11 @@
     "plugins": [
       "prettier-plugin-tailwindcss"
     ],
-    "tailwindConfig": "./tailwind.config.ts"
+    "tailwindStylesheet": "./src/app/css/index.css"
   },
   "dependencies": {
+    "@ai-sdk/openai-compatible": "^3.0.53",
+    "@ai-sdk/react": "^4.0.110",
     "@clack/prompts": "^0.7.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@neondatabase/serverless": "^1.1.0",
@@ -107,14 +116,16 @@
     "@tailwindcss/postcss": "^4.1.14",
     "@tailwindcss/typography": "^0.5.16",
     "@types/lodash": "^4.14.185",
+    "@types/nodemailer": "^8.0.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "@types/react-scroll": "^1.8.6",
     "@types/react-syntax-highlighter": "^15.5.7",
     "@types/refractor": "^3.0.2",
     "@types/ws": "^8.18.1",
-    "@vercel/blob": "^1.1.1",
+    "@vercel/nft": "^1.11.0",
     "@vitejs/plugin-react": "^4.5.2",
+    "ai": "^7.0.107",
     "archiver": "^5.3.1",
     "chalk": "^4.1.2",
     "chokidar": "^3.5.3",
@@ -136,6 +147,7 @@
     "next-auth": "^4.24.15",
     "next-themes": "^0.4.4",
     "node-html-parser": "^6.1.4",
+    "nodemailer": "^7.0.13",
     "pg": "^8.22.0",
     "postcss": "^8.4.16",
     "prettier": "^3.4.2",
@@ -155,8 +167,7 @@
     "vaul": "^1.1.2",
     "vite": "^6.3.5",
     "ws": "^8.18.3",
-    "yargs": "^17.7.2",
-    "zod": "^4.4.3"
+    "yargs": "^17.7.2"
   },
   "peerDependencies": {
     "typescript": ">=5.6 <7"
@@ -166,7 +177,7 @@
     "@types/cross-spawn": "^6.0.2",
     "@types/fs-extra": "^11.0.4",
     "@types/handlebars": "^4.1.0",
-    "@types/node": "^20.11.18",
+    "@types/node": "^22.0.0",
     "@types/pg": "^8.20.0",
     "@types/yargs": "^17.0.33",
     "drizzle-kit": "^0.31.10",

package/src/ai/README.md

@@ -0,0 +1,42 @@
+# AI Module
+
+The connection contract behind the docs assistant. `runtime.ai.connections` declares every endpoint
+and model a reader can reach. A reader supplies a key for a declared connection and nothing else, so
+the server never calls a URL a reader chose.
+
+Every connection speaks the OpenAI-compatible `/chat/completions` API. A connection that fits
+nothing else names a `defineAiProvider()` module instead of a base URL.
+
+Only provider selection, module location, option literals, and env-var _names_ are ever
+persisted. Secret _values_ are read from `process.env` at request time.
+
+## Files
+
+| File             | Purpose                                                                                                                                                   |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `connections.ts` | `AiConnectionSettings`/`AiSettings`, `resolveAiFromConfig()`, `parseAiConnections()`, `mergeAiConnections()`, `aiCredentialKind()`, model-id parse/format |
+| `define.ts`      | `defineAiProvider()` — typed identity helper for a custom, server-only provider module                                                                    |
+| `types.ts`       | `AiProvider`, `AiProviderContext`, `AiProviderFactory` — the pluggable provider contract                                                                  |
+
+## Credential states
+
+A connection declares how it is paid for, and this is never inferred from a missing key. Without the
+explicit third state, a reader gets a raw 401 from the provider instead of an instruction.
+
+| State         | Declaration               | Meaning                                                   |
+| ------------- | ------------------------- | --------------------------------------------------------- |
+| Service key   | `apiKey: fromEnv('NAME')` | The deployment pays. Every reader can use it.             |
+| No credential | neither field             | The endpoint needs none, such as a local Ollama.          |
+| User key      | `credential: 'user'`      | Each reader adds their own key for the declared endpoint. |
+
+## Resolution order
+
+1. The baked `runtime.ai.connections` list (`HANDOFF_AI_BAKED_CONNECTIONS`).
+2. `HANDOFF_AI_CONNECTIONS`, a JSON array read at request time, merged over the baked list by `id`.
+
+A reader's saved keys are not a third layer. They attach to a connection produced by these two
+steps, and cannot create, rename or redirect one.
+
+`runtime.ai.enabled` is config-only and baked, like `runtime.mcp`, so it decides whether the route
+and the header control exist at all. The connection list is not baked, so a deployment can change it
+without a rebuild.

package/src/ai/connections.ts

@@ -0,0 +1,189 @@
+/**
+ * AI connection resolution.
+ *
+ * `runtime.ai.connections` declares the whole surface a reader can reach. Mirrors
+ * {@link import('../registry/asset-storage/resolve')}: only provider selection, module location,
+ * non-secret options, and env-var *names* are ever persisted; secret *values* are read from
+ * `process.env` at request time.
+ *
+ * The list is deployment data rather than build shape, so `HANDOFF_AI_CONNECTIONS` can extend or
+ * replace the baked list at request time. A registry is built once and redeployed many times, and a
+ * new gateway should not need a rebuild.
+ */
+
+import { HandoffConfigError } from '../config/errors';
+import type { AiCredentialKind, HandoffAiConnection, ResolvedConfig } from '../types/config';
+
+/** A connection as it is baked and read back: env-var names, never secret values. */
+export interface AiConnectionSettings {
+  id: string;
+  label: string;
+  baseUrl?: string;
+  module?: string;
+  /** Name of the env var holding the deployment's own key. Its presence marks a service connection. */
+  apiKeyEnv?: string;
+  credential?: 'user';
+  models?: string[];
+  options?: Record<string, unknown>;
+}
+
+/** The resolved AI block: whether this build serves the assistant, and what it can reach. */
+export interface AiSettings {
+  enabled: boolean;
+  connections: AiConnectionSettings[];
+  defaultModel?: string;
+}
+
+/** A connection id addresses a model as `<id>/<model>`, so it cannot itself contain a slash. */
+const isUsableId = (id: unknown): id is string => typeof id === 'string' && id.trim().length > 0 && !id.includes('/');
+
+/**
+ * Which of the three credential states a connection declares. Derived from the declaration, never
+ * from a missing key: without the explicit `user` state, a connection that needs a reader's key
+ * would be indistinguishable from one that needs none.
+ */
+export const aiCredentialKind = (connection: AiConnectionSettings): AiCredentialKind => {
+  if (connection.credential === 'user') return 'user';
+  return connection.apiKeyEnv ? 'service' : 'none';
+};
+
+/** Split `<connectionId>/<model>`. Only the first slash separates them, since model ids carry slashes. */
+export const parseAiModelId = (value: string): { connectionId: string; model: string } | null => {
+  const separator = value.indexOf('/');
+  if (separator <= 0 || separator === value.length - 1) return null;
+  return { connectionId: value.slice(0, separator), model: value.slice(separator + 1) };
+};
+
+/** Join a connection id and a model into the address the client sends back. */
+export const formatAiModelId = (connectionId: string, model: string): string => `${connectionId}/${model}`;
+
+/** Normalize one authored or deployment-supplied connection, dropping anything unusable. */
+const toConnectionSettings = (input: unknown): AiConnectionSettings | null => {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const raw = input as Record<string, unknown>;
+  if (!isUsableId(raw.id)) return null;
+  const baseUrl = typeof raw.baseUrl === 'string' ? raw.baseUrl.trim() : undefined;
+  const module = typeof raw.module === 'string' ? raw.module.trim() : undefined;
+  if (!baseUrl && !module) return null;
+  // An authored config carries `apiKey` as a deferred `{ $env }` reference; a baked or
+  // deployment-supplied list carries the name it resolved to.
+  const reference = raw.apiKey as { $env?: unknown } | undefined;
+  const apiKeyEnv =
+    typeof raw.apiKeyEnv === 'string' && raw.apiKeyEnv.trim()
+      ? raw.apiKeyEnv.trim()
+      : typeof reference?.$env === 'string'
+        ? reference.$env
+        : undefined;
+  // A repeated model would be two picker entries for one choice, so the first occurrence wins.
+  const models = Array.isArray(raw.models)
+    ? [...new Set(raw.models.filter((model): model is string => typeof model === 'string' && !!model.trim()).map((model) => model.trim()))]
+    : [];
+  const options =
+    raw.options && typeof raw.options === 'object' && !Array.isArray(raw.options) ? (raw.options as Record<string, unknown>) : undefined;
+
+  return {
+    id: raw.id.trim(),
+    label: typeof raw.label === 'string' && raw.label.trim() ? raw.label.trim() : raw.id.trim(),
+    ...(baseUrl ? { baseUrl } : {}),
+    ...(module ? { module } : {}),
+    ...(apiKeyEnv ? { apiKeyEnv } : {}),
+    ...(raw.credential === 'user' ? { credential: 'user' as const } : {}),
+    ...(models.length ? { models } : {}),
+    ...(options ? { options } : {}),
+  };
+};
+
+/** Normalize a declared list, keeping the first entry for any repeated id. */
+const toConnectionList = (input: readonly unknown[] | undefined): AiConnectionSettings[] => {
+  const byId = new Map<string, AiConnectionSettings>();
+  for (const entry of input ?? []) {
+    const connection = toConnectionSettings(entry);
+    if (connection && !byId.has(connection.id)) byId.set(connection.id, connection);
+  }
+  return [...byId.values()];
+};
+
+const ignoredOverrides = new Set<string>();
+
+/**
+ * Merge a deployment-supplied list over the baked one by `id`: a matching id replaces the baked
+ * connection outright, and a new id is appended. Replacement rather than a field-wise merge, so a
+ * deployment that repoints a gateway cannot leave a stale model list or key name behind.
+ *
+ * A deployment-supplied connection can use only a `module` that the build includes.
+ */
+export const mergeAiConnections = (
+  baked: readonly AiConnectionSettings[],
+  overrides: readonly AiConnectionSettings[]
+): AiConnectionSettings[] => {
+  const byId = new Map(baked.map((connection) => [connection.id, connection]));
+  const bakedModules = new Set(baked.map((connection) => connection.module).filter(Boolean));
+  for (const connection of overrides) {
+    if (connection.module && !bakedModules.has(connection.module)) {
+      if (!ignoredOverrides.has(connection.id)) {
+        ignoredOverrides.add(connection.id);
+        console.warn(
+          `HANDOFF_AI_CONNECTIONS: connection "${connection.id}" is ignored, because the build does not include its module ` +
+            `"${connection.module}". Declare the connection in runtime.ai.connections.`
+        );
+      }
+      continue;
+    }
+    byId.set(connection.id, connection);
+  }
+  return [...byId.values()];
+};
+
+/** Parse the `HANDOFF_AI_CONNECTIONS` JSON array. A malformed value is ignored rather than fatal. */
+export const parseAiConnections = (raw: string | undefined): AiConnectionSettings[] => {
+  if (!raw?.trim()) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? toConnectionList(parsed) : [];
+  } catch {
+    return [];
+  }
+};
+
+/**
+ * Whether this build serves the assistant. The `ai` block is the opt-in; `enabled: false` turns it
+ * back off. Config-only and baked, like `runtime.mcp`.
+ */
+export const isAiEnabled = (config: Pick<ResolvedConfig, 'runtime'> | null | undefined): boolean =>
+  Boolean(config?.runtime?.ai) && config?.runtime?.ai?.enabled !== false;
+
+/**
+ * Resolve the AI settings from a loaded config (CLI/build side).
+ *
+ * An authored connection that cannot be used fails the build rather than disappearing. A deployment
+ * list stays lenient by contrast: a bad `HANDOFF_AI_CONNECTIONS` entry must not take the server down.
+ */
+export const resolveAiFromConfig = (config: ResolvedConfig | null | undefined): AiSettings => {
+  const authored = (config?.runtime?.ai?.connections ?? []) as readonly HandoffAiConnection[];
+  const fail = (problem: string, ids: readonly unknown[]): never => {
+    throw new HandoffConfigError(
+      `Config "runtime.ai.connections": ${problem} (${ids.map((id) => JSON.stringify(id ?? null)).join(', ')}).`
+    );
+  };
+
+  const normalized = authored.map((connection) => ({ authored: connection, settings: toConnectionSettings(connection) }));
+  const unusable = normalized.filter((entry) => !entry.settings);
+  if (unusable.length > 0) {
+    fail(
+      'every connection needs an "id" without a slash, and either a "baseUrl" or a "module"',
+      unusable.map((entry) => entry.authored?.id)
+    );
+  }
+
+  const ids = normalized.map((entry) => entry.settings!.id);
+  const duplicates = ids.filter((id, index) => ids.indexOf(id) !== index);
+  if (duplicates.length > 0) {
+    fail('a connection id must be unique, because it is half of every model address', duplicates);
+  }
+
+  return {
+    enabled: isAiEnabled(config),
+    connections: normalized.map((entry) => entry.settings!),
+    defaultModel: config?.runtime?.ai?.defaultModel?.trim() || undefined,
+  };
+};

package/src/ai/define.ts

@@ -0,0 +1,15 @@
+/**
+ * Typed identity helper for custom AI providers (mirrors `defineStorageProvider`): a consumer
+ * default-exports its result from a **server-only** module and points a connection's `module` at
+ * it. It must be its own module (not an inline `defineConfig` function) so the build can trace it
+ * into the deployed registry. The default export may be the provider object, or a factory
+ * `(context) => AiProvider` when it needs its options, env or the resolved key.
+ */
+
+import type { AiProvider, AiProviderFactory } from './types';
+
+export function defineAiProvider(provider: AiProvider): AiProvider;
+export function defineAiProvider(factory: AiProviderFactory): AiProviderFactory;
+export function defineAiProvider(input: AiProvider | AiProviderFactory): AiProvider | AiProviderFactory {
+  return input;
+}

package/src/ai/types.ts

@@ -0,0 +1,30 @@
+/**
+ * Server-only AI provider contract for connections that are not OpenAI-compatible.
+ *
+ * Every built-in connection speaks the OpenAI-compatible `/chat/completions` API and needs no
+ * custom module — Ollama, LiteLLM, OpenRouter, vLLM, LM Studio and Azure OpenAI all serve it, and each of
+ * them fronts Anthropic, Google and xAI models. A provider that fits nothing else names a
+ * {@link defineAiProvider} module instead of a base URL.
+ */
+
+import type { LanguageModel } from 'ai';
+
+/** Context passed to a custom provider factory. */
+export interface AiProviderContext {
+  /** The connection's `options`, with each `fromEnv()` reference replaced by its value. */
+  options: Record<string, unknown>;
+  env: NodeJS.ProcessEnv;
+  /**
+   * The resolved key for this request: the deployment's own key for a service connection, or the
+   * reader's saved key for a `credential: 'user'` connection. Undefined when neither applies.
+   */
+  apiKey?: string;
+}
+
+/** The pluggable provider contract: resolve one of the connection's declared models. */
+export interface AiProvider {
+  languageModel(modelId: string): LanguageModel;
+}
+
+/** A custom provider may export the provider directly or a factory that builds it from its context. */
+export type AiProviderFactory = (context: AiProviderContext) => AiProvider | Promise<AiProvider>;

package/src/app/components/AiAssistant/AiAssistantPanel.tsx

@@ -0,0 +1,144 @@
+'use client';
+
+import { X } from 'lucide-react';
+import * as React from 'react';
+
+import { cn } from '../../lib/utils';
+import { Button } from '../ui/button';
+import { Sheet, SheetContent, SheetDescription, SheetTitle } from '../ui/sheet';
+import { AiConversation } from './AiConversation';
+import { DOCK_WIDTH_VAR, fitWidth, MAX_WIDTH, MIN_WIDTH, type DockState } from './dockState';
+
+/**
+ * Where the conversation sits: a column pinned to the right of the page, not a modal, so the reader
+ * can browse the docs and read the answer at once. A narrow viewport has no room for two columns,
+ * so the same conversation moves into a sheet.
+ *
+ * Nothing here owns the conversation. {@link useAiChat} does, so none of these moves can discard it.
+ */
+
+const RESIZE_STEP = 16;
+
+const IconButton: React.FC<{ label: string; onClick: () => void; children: React.ReactNode }> = ({ label, onClick, children }) => (
+  <Button type="button" variant="ghost" size="icon-sm" onClick={onClick} title={label} aria-label={label} className="text-muted-foreground">
+    {children}
+  </Button>
+);
+
+/**
+ * A drag writes the width straight to `--ai-dock-width` and reports it to React only on release: a
+ * state change per pointer move would re-render the whole page under the dock once a frame. The
+ * `data-ai-dock-resizing` flag drops the transition for the drag, so the edge tracks the pointer.
+ *
+ * The dock is anchored right, so the width is the pointer's distance from that edge.
+ */
+const ResizeHandle: React.FC<{ width: number; onCommit: (width: number) => void }> = ({ width, onCommit }) => {
+  const onPointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
+    event.preventDefault();
+    const root = document.documentElement;
+    let next = width;
+
+    const onMove = (move: PointerEvent) => {
+      next = fitWidth(window.innerWidth - move.clientX);
+      root.style.setProperty(DOCK_WIDTH_VAR, `${next}px`);
+    };
+    const onUp = () => {
+      delete root.dataset.aiDockResizing;
+      window.removeEventListener('pointermove', onMove);
+      window.removeEventListener('pointerup', onUp);
+      onCommit(next);
+    };
+
+    root.dataset.aiDockResizing = 'true';
+    window.addEventListener('pointermove', onMove);
+    window.addEventListener('pointerup', onUp);
+  };
+
+  return (
+    <div
+      role="separator"
+      aria-orientation="vertical"
+      aria-label="Resize the assistant"
+      aria-valuemin={MIN_WIDTH}
+      aria-valuemax={MAX_WIDTH}
+      aria-valuenow={width}
+      tabIndex={0}
+      onPointerDown={onPointerDown}
+      onKeyDown={(event) => {
+        if (event.key === 'ArrowLeft') onCommit(fitWidth(width + RESIZE_STEP));
+        else if (event.key === 'ArrowRight') onCommit(fitWidth(width - RESIZE_STEP));
+        else return;
+        event.preventDefault();
+      }}
+      // Inside the panel: the dock clips its overflow, so a handle across the border loses half its
+      // hit area.
+      className="outline-hidden absolute inset-y-0 left-0 z-10 w-1.5 cursor-col-resize transition-colors hover:bg-border focus-visible:bg-ring"
+    />
+  );
+};
+
+export const AiAssistantPanel: React.FC<{
+  state: DockState;
+  isMobile: boolean;
+  onChange: (next: Partial<DockState>) => void;
+}> = ({ state, isMobile, onChange }) => {
+  // Keep the scroll position and an unsent draft across a close, without costing a reader who never
+  // opens the assistant anything.
+  const [everOpened, setEverOpened] = React.useState(state.open);
+  const close = () => onChange({ open: false });
+
+  React.useEffect(() => {
+    if (state.open) setEverOpened(true);
+  }, [state.open]);
+
+  if (isMobile) {
+    return (
+      <Sheet open={state.open} onOpenChange={(open) => onChange({ open })}>
+        <SheetContent side="right" className="w-full gap-0 p-0 sm:max-w-md [&>button:first-of-type]:hidden">
+          <SheetTitle className="sr-only">Ask the design system</SheetTitle>
+          <SheetDescription className="sr-only">
+            Answers come from the components, tokens and documentation of this design system.
+          </SheetDescription>
+          <AiConversation
+            active={state.open}
+            controls={
+              <IconButton label="Close the assistant" onClick={close}>
+                <X className="h-4 w-4" />
+              </IconButton>
+            }
+          />
+        </SheetContent>
+      </Sheet>
+    );
+  }
+
+  return (
+    <aside
+      aria-label="Design system assistant"
+      // The closed dock stays mounted at zero width, so `inert` has to keep it out of the tab order
+      // and the accessibility tree.
+      inert={!state.open}
+      style={{ width: `var(${DOCK_WIDTH_VAR}, 0px)` }}
+      className={cn(
+        // Below the app header, which reaches across the dock's column through `.ai-dock-bleed`.
+        'ai-dock top-17 fixed bottom-0 right-0 z-40 flex flex-col overflow-hidden bg-background',
+        state.open && 'border-l'
+      )}
+    >
+      {/* Kept mounted after the first open, so closing preserves the scroll position and an unsent draft. */}
+      {everOpened && (
+        <div className="absolute inset-y-0 right-0 flex min-h-0 flex-col" style={{ width: `${state.width}px` }}>
+          <AiConversation
+            active={state.open}
+            controls={
+              <IconButton label="Close the assistant" onClick={close}>
+                <X className="h-4 w-4" />
+              </IconButton>
+            }
+          />
+        </div>
+      )}
+      {state.open && <ResizeHandle width={state.width} onCommit={(width) => onChange({ width })} />}
+    </aside>
+  );
+};