jamdesk 1.0.13 → 1.0.14

package/vendored/lib/vector-store.ts

@@ -0,0 +1,213 @@
+/**
+ * Upstash Vector Store
+ *
+ * Manages vector embeddings for AI chat. Each project gets its own namespace
+ * in the Upstash Vector index. Upstash handles embedding generation
+ * server-side — we send raw text, not pre-computed vectors.
+ *
+ * Used in two contexts:
+ * 1. Build time: upsertChunks() stores page chunks after a successful build
+ * 2. Chat API: querySimilarChunks() retrieves relevant context for user queries
+ */
+import { Index, FusionAlgorithm, WeightingStrategy, QueryMode } from '@upstash/vector';
+import type { EmbeddingChunk } from './embedding-chunker.js';
+
+export interface ChunkMetadata {
+  [key: string]: unknown;
+  pageSlug: string;
+  sectionHeading: string;
+  pageTitle: string;
+  content: string;
+}
+
+/** Upstash limit per upsert call */
+const BATCH_SIZE = 100;
+
+/**
+ * Upstash metadata limit is 48KB per record. The content field in metadata
+ * is used for LLM context retrieval, while the `data` field (no limit) is
+ * used for embedding generation. Truncate metadata content to stay under limit.
+ */
+const MAX_METADATA_CONTENT_CHARS = 10000;
+
+/** Hybrid search parameters — DBSF fusion with IDF-weighted BM25 */
+const HYBRID_QUERY_OPTS = {
+  queryMode: QueryMode.HYBRID,
+  fusionAlgorithm: FusionAlgorithm.DBSF,
+  weightingStrategy: WeightingStrategy.IDF,
+} as const;
+
+/**
+ * Minimum similarity score — below this threshold results are near-random
+ * and would give the LLM poor context. Initially set for cosine similarity;
+ * may need recalibration after switching to DBSF/RRF fusion scores.
+ */
+const MIN_SCORE = 0.3;
+
+/** Max chunks per page — ensures diverse results across pages */
+const MAX_CHUNKS_PER_PAGE = 3;
+
+/** Create a namespaced Upstash Vector index for a project. */
+function getNamespace(projectId: string) {
+  const index = new Index({
+    url: process.env.UPSTASH_VECTOR_REST_URL!,
+    token: process.env.UPSTASH_VECTOR_REST_TOKEN!,
+  });
+  return index.namespace(projectId);
+}
+
+/**
+ * Replace all vectors for a project with fresh chunks.
+ *
+ * Resets the namespace first (deletes all existing vectors), then upserts
+ * new chunks in batches of 100. Upstash generates embeddings from the
+ * `data` field — no need for a separate embedding model.
+ *
+ * Note: This is NOT safe for concurrent calls on the same project — reset()
+ * could clear another build's partially-upserted data. The build queue system
+ * guarantees one build per project at a time, preventing this race condition.
+ */
+export async function upsertChunks(
+  projectId: string,
+  chunks: EmbeddingChunk[],
+): Promise<void> {
+  const ns = getNamespace(projectId);
+
+  await ns.reset();
+
+  for (let i = 0; i < chunks.length; i += BATCH_SIZE) {
+    const batch = chunks.slice(i, i + BATCH_SIZE);
+    await ns.upsert(
+      batch.map(c => ({
+        id: c.id,
+        data: c.content,
+        metadata: {
+          pageSlug: c.pageSlug,
+          sectionHeading: c.sectionHeading,
+          pageTitle: c.pageTitle,
+          content: c.content.length > MAX_METADATA_CONTENT_CHARS
+            ? c.content.slice(0, MAX_METADATA_CONTENT_CHARS) + '...'
+            : c.content,
+        } satisfies ChunkMetadata,
+      })),
+    );
+  }
+}
+
+/**
+ * Strip common question/request phrasing to extract the core topic.
+ * Long queries like "How do I make an analytics call - give me a javascript example"
+ * embed poorly — the request-pattern words ("give me", "example") dilute the topic signal.
+ * Extracting just the topic ("analytics call") produces much better vector matches.
+ *
+ * Returns the stripped topic, or null if stripping didn't meaningfully shorten the query.
+ */
+export function extractTopicQuery(queryText: string): string | null {
+  let topic = queryText;
+
+  // Strip leading question patterns
+  topic = topic.replace(/^(how (do|can|would|should) (i|you|we)|can (i|you|we)|what('s| is| are)|where (do|can|is|are)|show me|tell me|give me|explain|describe|help me)\b/i, '');
+
+  // Strip trailing request patterns (after dash, comma, or period)
+  topic = topic.replace(/\s*[-–—,.]\s*(give me|show me|provide|include|with)\b.*$/i, '');
+
+  // Strip request-type suffixes
+  topic = topic.replace(/\b(give me|show me|provide|include)\s+(a|an|some|the)?\s*(javascript|typescript|python|code|curl)?\s*(example|sample|snippet|demo)s?\b/gi, '');
+
+  // Strip filler words
+  topic = topic.replace(/\b(please|just|basically|simply|actually)\b/gi, '');
+
+  // Clean up extra whitespace and trim
+  topic = topic.replace(/\s+/g, ' ').trim();
+
+  // Only use the topic query if it's meaningfully shorter (at least 30% shorter)
+  if (!topic || topic.length > queryText.length * 0.7) return null;
+  return topic;
+}
+
+/** Query with hybrid mode, falling back to dense-only if hybrid is not supported */
+async function queryWithFallback(
+  ns: ReturnType<typeof getNamespace>,
+  params: { data: string; topK: number; includeMetadata: true },
+): Promise<Array<{ id: string | number; score: number; metadata?: ChunkMetadata }>> {
+  try {
+    return await ns.query<ChunkMetadata>({ ...params, ...HYBRID_QUERY_OPTS });
+  } catch (err) {
+    // Hybrid not supported on this index — fall back to dense-only
+    console.warn('[vector-store] Hybrid query failed, falling back to dense-only:', String(err));
+    return await ns.query<ChunkMetadata>({ ...params, queryMode: QueryMode.DENSE });
+  }
+}
+
+type RawResult = { id: string | number; score: number; metadata?: ChunkMetadata };
+
+/**
+ * Deduplicate and filter raw vector results into scored chunks.
+ * Filters out low-score results and limits chunks per page for diversity.
+ * Accepts multiple result lists — earlier lists take priority.
+ */
+function filterAndMerge(
+  resultSets: RawResult[][],
+  topK: number,
+): Array<ChunkMetadata & { score: number }> {
+  const seen = new Set<string>();
+  const pageCount = new Map<string, number>();
+  const merged: Array<ChunkMetadata & { score: number }> = [];
+
+  for (const results of resultSets) {
+    for (const r of results) {
+      if (merged.length >= topK) return merged;
+      if (!r.metadata || r.score < MIN_SCORE) continue;
+
+      const id = String(r.id);
+      if (seen.has(id)) continue;
+
+      const count = pageCount.get(r.metadata.pageSlug) ?? 0;
+      if (count >= MAX_CHUNKS_PER_PAGE) continue;
+
+      seen.add(id);
+      pageCount.set(r.metadata.pageSlug, count + 1);
+      merged.push({ ...r.metadata, score: r.score });
+    }
+  }
+
+  return merged;
+}
+
+/**
+ * Find chunks most similar to a query string.
+ *
+ * Uses a dual-query strategy for long queries: runs the full query AND an
+ * extracted topic-only version in parallel, then merges results. This prevents
+ * request-pattern words (e.g. "give me a javascript example") from diluting
+ * the topic signal in the embedding.
+ *
+ * Returns up to `topK` results with their similarity scores,
+ * filtering out any results with missing metadata.
+ */
+export async function querySimilarChunks(
+  projectId: string,
+  queryText: string,
+  topK = 5,
+): Promise<Array<ChunkMetadata & { score: number }>> {
+  const ns = getNamespace(projectId);
+  const queryParams = { topK, includeMetadata: true as const };
+
+  const topicQuery = extractTopicQuery(queryText);
+
+  // Dual-query: topic query is the PRIMARY source (better topical relevance);
+  // the full query fills remaining slots with unique results only.
+  if (topicQuery) {
+    const [fullResults, topicResults] = await Promise.all([
+      queryWithFallback(ns, { data: queryText, ...queryParams }),
+      queryWithFallback(ns, { data: topicQuery, ...queryParams }),
+    ]);
+
+    // Topic results first for best topical relevance
+    return filterAndMerge([topicResults, fullResults], topK);
+  }
+
+  // Simple single-query path for short/simple queries
+  const results = await queryWithFallback(ns, { data: queryText, ...queryParams });
+  return filterAndMerge([results], topK);
+}

package/vendored/schema/docs-schema.json

@@ -13,6 +13,10 @@
             "default": "https://www.jamdesk.com/docs.json",
             "description": "The URL to the JSON schema file for validation"
           },
+          "projectId": {
+            "type": "string",
+            "description": "Jamdesk project identifier. Automatically set by jamdesk deploy."
+          },
           "name": {
             "type": "string",
             "minLength": 1,
@@ -1363,6 +1367,23 @@
             },
             "additionalProperties": false,
             "description": "Configure page metadata display settings"
+          },
+          "chat": {
+            "type": "object",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "description": "Enable AI-powered chat assistant (default: true). Set to false to disable.",
+                "default": true
+              },
+              "starterQuestions": {
+                "type": "array",
+                "items": { "type": "string", "minLength": 5, "maxLength": 200 },
+                "maxItems": 4,
+                "description": "Suggested questions shown in chat empty state. Auto-generated by AI during builds when omitted. Set to [] to disable."
+              }
+            },
+            "additionalProperties": false
           }
         },
         "required": [
@@ -1383,6 +1404,9 @@
           "$schema": {
             "$ref": "#/anyOf/0/properties/$schema"
           },
+          "projectId": {
+            "$ref": "#/anyOf/0/properties/projectId"
+          },
           "name": {
             "$ref": "#/anyOf/0/properties/name"
           },
@@ -1460,6 +1484,9 @@
           },
           "metadata": {
             "$ref": "#/anyOf/0/properties/metadata"
+          },
+          "chat": {
+            "$ref": "#/anyOf/0/properties/chat"
           }
         },
         "required": [
@@ -1480,6 +1507,9 @@
           "$schema": {
             "$ref": "#/anyOf/0/properties/$schema"
           },
+          "projectId": {
+            "$ref": "#/anyOf/0/properties/projectId"
+          },
           "name": {
             "$ref": "#/anyOf/0/properties/name"
           },
@@ -1557,6 +1587,9 @@
           },
           "metadata": {
             "$ref": "#/anyOf/0/properties/metadata"
+          },
+          "chat": {
+            "$ref": "#/anyOf/0/properties/chat"
           }
         },
         "required": [

package/vendored/scripts/dev-project.cjs

@@ -379,6 +379,7 @@ async function runDev() {
     JAMDESK_PROJECTS_DIR: projectsDir,  // Pass the resolved projects directory to child scripts
     HOST_AT_DOCS: hostAtDocs ? 'true' : 'false',  // Pass to Next.js config
     NEXT_PUBLIC_BASE_PATH: hostAtDocs ? '/docs' : '',  // Pass to client components for asset URLs
+    NEXT_PUBLIC_PROJECT_SLUG: effectiveProjectName,  // Pass to chat hook for local dev API routing
   };
 
   try {
@@ -451,6 +452,11 @@ async function runDev() {
       env,
     });
 
+    // Note: No file watcher needed for docs.json. In dev mode, getDocsConfig()
+    // reads directly from the project source (not public/docs.json) with mtime-based
+    // cache invalidation. Edits are picked up automatically on browser refresh.
+    // Writing to public/ during dev triggers Turbopack recompilation hangs.
+
     // Step 4: Run Next.js dev server
     console.log(`\n🚀 Starting dev server on port ${port}...`);
     // Get first page and OpenAPI config from docs.json (reuse projectDocsJson from step 1)

package/vendored/shared/types.ts

@@ -12,18 +12,19 @@ export interface BuildParams {
   projectId: string;
   buildId: string;
   slug: string;
-  repoFullName: string;
-  branch: string;
-  installationId: number;
+  repoFullName?: string;     // Optional for CLI builds
+  branch?: string;           // Optional for CLI builds
+  installationId?: number;   // Optional for CLI builds
   triggeredBy: string;
-  commitSha: string;
-  commitMessage: string;
+  commitSha?: string;        // Optional for CLI builds
+  commitMessage?: string;    // Optional for CLI builds
   fullRebuild?: boolean;  // If true, forces full R2 upload (ignores manifest)
   docsPath?: string | null;  // Monorepo: path to docs.json directory (e.g., "jamdesk")
   domain?: string;  // Project's custom domain or subdomain (e.g., "docs.acme.com" or "acme.jamdesk.app")
   showBranding?: boolean;  // Show "Powered by Jamdesk" in footer (defaults to true)
   hostAtDocs?: boolean;  // URL structure: true = /docs/*, false = root /*
   autoMigrate?: boolean;  // If true, auto-convert deprecated components during build
+  tarballKey?: string;       // R2 key for CLI-uploaded tarball
 }
 
 export interface ErrorDetails {

package/vendored/tailwind.config.ts

@@ -33,6 +33,15 @@ export default {
         'theme-code-bg': 'var(--color-code-bg)',
         'theme-code-text': 'var(--color-code-text)',
       },
+      keyframes: {
+        'fd-fade-in': {
+          from: { opacity: '0' },
+          to: { opacity: '1' },
+        },
+      },
+      animation: {
+        'fd-fade-in': 'fd-fade-in 0.15s ease-in forwards',
+      },
     },
   },
 }

package/vendored/themes/jam/variables.css

@@ -216,8 +216,8 @@ body[data-theme="jam"]:not(.dark) main {
   background-color: transparent !important;
 }
 
-/* Target wrapper divs that contain the main content */
-body[data-theme="jam"]:not(.dark) > div > div.flex {
+/* Target wrapper divs that contain the main content (exclude chat panel) */
+body[data-theme="jam"]:not(.dark) > div > div.flex:not([role="dialog"]):not(:has([data-chat-panel])) {
   background-color: transparent !important;
 }