@tanstack/ai-code-mode-snippets 0.3.14

package/src/generate-snippet-types.ts

@@ -0,0 +1,162 @@
+import type { Snippet } from './types'
+
+/**
+ * Convert a JSON Schema to a TypeScript type string
+ */
+function schemaToType(schema: Record<string, unknown>): string {
+  if (typeof schema !== 'object') {
+    return 'unknown'
+  }
+
+  const schemaType = schema.type
+
+  // Handle basic types
+  if (schemaType === 'string') return 'string'
+  if (schemaType === 'number' || schemaType === 'integer') return 'number'
+  if (schemaType === 'boolean') return 'boolean'
+  if (schemaType === 'null') return 'null'
+
+  // Handle arrays
+  if (schemaType === 'array') {
+    const items = schema.items as Record<string, unknown> | undefined
+    const itemType = items ? schemaToType(items) : 'unknown'
+    return `Array<${itemType}>`
+  }
+
+  // Handle objects with properties
+  if (schemaType === 'object' && schema.properties) {
+    const properties = schema.properties as Record<
+      string,
+      Record<string, unknown>
+    >
+    const required = new Set(
+      (schema.required as Array<string> | undefined) ?? [],
+    )
+
+    const props = Object.entries(properties)
+      .map(([key, propSchema]) => {
+        const optional = required.has(key) ? '' : '?'
+        const propType = schemaToType(propSchema)
+        // Handle property names that need quoting
+        const safeName = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key)
+          ? key
+          : `"${key}"`
+        return `  ${safeName}${optional}: ${propType};`
+      })
+      .join('\n')
+
+    return `{\n${props}\n}`
+  }
+
+  // Handle enums
+  if (schema.enum) {
+    const enumValues = schema.enum as Array<unknown>
+    return enumValues.map((v) => JSON.stringify(v)).join(' | ')
+  }
+
+  // Handle union types (anyOf, oneOf)
+  if (schema.anyOf || schema.oneOf) {
+    const variants = (schema.anyOf || schema.oneOf) as Array<
+      Record<string, unknown>
+    >
+    return variants.map((v) => schemaToType(v)).join(' | ')
+  }
+
+  // Handle type arrays (e.g., ["string", "null"])
+  if (Array.isArray(schemaType)) {
+    return schemaType
+      .map((t) => {
+        if (t === 'string') return 'string'
+        if (t === 'number' || t === 'integer') return 'number'
+        if (t === 'boolean') return 'boolean'
+        if (t === 'null') return 'null'
+        if (t === 'array') return 'Array<unknown>'
+        if (t === 'object') return 'object'
+        return 'unknown'
+      })
+      .join(' | ')
+  }
+
+  // Fallback for unknown schemas
+  return 'unknown'
+}
+
+/**
+ * Capitalize the first letter of a string
+ */
+function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1)
+}
+
+/**
+ * Convert snake_case to PascalCase
+ */
+function toPascalCase(str: string): string {
+  return str
+    .split('_')
+    .map((part) => capitalize(part))
+    .join('')
+}
+
+/**
+ * Generate TypeScript type stubs for snippets.
+ * These are included in the system prompt so the LLM knows
+ * the exact type signatures of available snippets.
+ */
+export function generateSnippetTypes(snippets: Array<Snippet>): string {
+  const declarations: Array<string> = []
+
+  for (const snippet of snippets) {
+    const baseName = toPascalCase(snippet.name)
+    const inputTypeName = `Snippet${baseName}Input`
+    const outputTypeName = `Snippet${baseName}Output`
+
+    // Generate input type
+    const inputType = schemaToType(snippet.inputSchema)
+    if (
+      snippet.inputSchema.type === 'object' &&
+      snippet.inputSchema.properties &&
+      Object.keys(snippet.inputSchema.properties).length > 0
+    ) {
+      declarations.push(`interface ${inputTypeName} ${inputType}`)
+    }
+
+    // Generate output type
+    const outputType = schemaToType(snippet.outputSchema)
+    if (
+      snippet.outputSchema.type === 'object' &&
+      snippet.outputSchema.properties &&
+      Object.keys(snippet.outputSchema.properties).length > 0
+    ) {
+      declarations.push(`interface ${outputTypeName} ${outputType}`)
+    }
+
+    // Determine type references
+    const inputRef =
+      snippet.inputSchema.type === 'object' &&
+      snippet.inputSchema.properties &&
+      Object.keys(snippet.inputSchema.properties).length > 0
+        ? inputTypeName
+        : inputType
+
+    const outputRef =
+      snippet.outputSchema.type === 'object' &&
+      snippet.outputSchema.properties &&
+      Object.keys(snippet.outputSchema.properties).length > 0
+        ? outputTypeName
+        : outputType
+
+    // Generate function declaration with JSDoc
+    const hintsDoc = snippet.usageHints.map((h) => ` * @hint ${h}`).join('\n')
+
+    declarations.push(
+      `/**
+ * ${snippet.description}
+${hintsDoc}
+ */
+declare function snippet_${snippet.name}(input: ${inputRef}): Promise<${outputRef}>;`,
+    )
+  }
+
+  return declarations.join('\n\n')
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+// Main entry point
+export {
+  codeModeWithSnippets,
+  createCodeModeWithSnippetsConfig,
+} from './code-mode-with-snippets'
+export type {
+  CodeModeWithSnippetsOptions,
+  CodeModeWithSnippetsResult,
+} from './code-mode-with-snippets'
+
+// Trust strategies
+export {
+  createDefaultTrustStrategy,
+  createAlwaysTrustedStrategy,
+  createRelaxedTrustStrategy,
+  createCustomTrustStrategy,
+} from './trust-strategies'
+export type { TrustStrategy } from './trust-strategies'
+
+// Snippet selection
+export { selectRelevantSnippets } from './select-relevant-snippets'
+
+// Snippets to tools (for direct calling)
+export { snippetsToTools, snippetToTool } from './snippets-to-tools'
+export type { SnippetToToolOptions } from './snippets-to-tools'
+
+// Snippets to bindings (for sandbox injection - legacy)
+export {
+  snippetsToBindings,
+  snippetsToSimpleBindings,
+} from './snippets-to-bindings'
+
+// Snippet management tools
+export { createSnippetManagementTools } from './create-snippet-management-tools'
+
+// System prompt generation
+export { createSnippetsSystemPrompt } from './create-snippets-system-prompt'
+
+// Type generation
+export { generateSnippetTypes } from './generate-snippet-types'
+
+// Storage implementations
+//
+// Only the worker/browser-safe in-memory storage is re-exported from the root
+// entry. The Node-only file storage (`createFileSnippetStorage`) imports
+// `node:fs` / `node:path`, so it lives behind the `@tanstack/ai-code-mode-snippets/storage`
+// subpath to keep this root export safe for Cloudflare Workers and browser bundlers.
+export { createMemorySnippetStorage } from './storage/memory-storage'
+export type { MemorySnippetStorageOptions } from './storage/memory-storage'
+
+// All types
+export type {
+  Snippet,
+  SnippetIndexEntry,
+  SnippetStorage,
+  SnippetsConfig,
+  SnippetStats,
+  TrustLevel,
+  SnippetBinding,
+} from './types'

package/src/select-relevant-snippets.ts

@@ -0,0 +1,136 @@
+import { chat } from '@tanstack/ai'
+import type { AnyTextAdapter, ModelMessage, StreamChunk } from '@tanstack/ai'
+import type { Snippet, SnippetIndexEntry, SnippetStorage } from './types'
+
+interface SelectRelevantSnippetsOptions {
+  /**
+   * Text adapter for snippet selection (should be a cheap/fast model)
+   */
+  adapter: AnyTextAdapter
+
+  /**
+   * Current conversation messages
+   */
+  messages: Array<ModelMessage>
+
+  /**
+   * Snippet index (lightweight metadata)
+   */
+  snippetIndex: Array<SnippetIndexEntry>
+
+  /**
+   * Maximum number of snippets to select
+   */
+  maxSnippets: number
+
+  /**
+   * Storage to load full snippet data
+   */
+  storage: SnippetStorage
+}
+
+/**
+ * Use a cheap/fast LLM to select which snippets are relevant for the current conversation
+ */
+export async function selectRelevantSnippets({
+  adapter,
+  messages,
+  snippetIndex,
+  maxSnippets,
+  storage,
+}: SelectRelevantSnippetsOptions): Promise<Array<Snippet>> {
+  // Early exit conditions
+  if (snippetIndex.length === 0) return []
+  if (messages.length === 0) return []
+
+  // Build context from recent messages (last 5)
+  const recentMessages = messages.slice(-5)
+  const recentContext = recentMessages
+    .map((m) => {
+      let content: string
+      if (typeof m.content === 'string') {
+        content = m.content
+      } else if (Array.isArray(m.content)) {
+        // Handle content parts (text, images, etc.)
+        content = m.content
+          .map((part: unknown) => {
+            if (typeof part === 'string') return part
+            if (part && typeof part === 'object' && 'text' in part)
+              return (part as { text: string }).text
+            return '[non-text content]'
+          })
+          .join(' ')
+      } else {
+        content = '[complex content]'
+      }
+      return `${m.role}: ${content}`
+    })
+    .join('\n')
+
+  // Build snippet catalog for selection prompt
+  const snippetCatalog = snippetIndex
+    .map((s) => {
+      const hints = s.usageHints.length > 0 ? ` (${s.usageHints[0]})` : ''
+      return `- ${s.name}: ${s.description}${hints}`
+    })
+    .join('\n')
+
+  // Ask cheap model to select relevant snippets
+  const selectionPrompt = `Given this conversation context:
+---
+${recentContext}
+---
+
+Which of these snippets (if any) would be useful for the next response? Return a JSON array of snippet names, max ${maxSnippets}. Return [] if none are relevant.
+
+Available snippets:
+${snippetCatalog}
+
+Respond with only the JSON array, no explanation. Example: ["snippet_name_1", "snippet_name_2"]`
+
+  try {
+    // Use chat to get the selection
+    const stream = chat({
+      adapter,
+      messages: [
+        {
+          role: 'user',
+          content: selectionPrompt,
+        },
+      ],
+    })
+
+    // Collect the full response
+    let responseText = ''
+    for await (const chunk of stream as AsyncIterable<StreamChunk>) {
+      if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
+        responseText += chunk.delta
+      }
+    }
+
+    // Parse the JSON response
+    // Handle potential markdown code blocks
+    let jsonText = responseText.trim()
+    if (jsonText.startsWith('```')) {
+      // Remove markdown code block
+      jsonText = jsonText.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '')
+    }
+
+    const selectedNames: Array<string> = JSON.parse(jsonText)
+
+    if (!Array.isArray(selectedNames)) {
+      return []
+    }
+
+    // Load full snippet data for selected snippets
+    const selectedSnippets = await Promise.all(
+      selectedNames.slice(0, maxSnippets).map((name) => storage.get(name)),
+    )
+
+    return selectedSnippets.filter((s): s is Snippet => s !== null)
+  } catch (error) {
+    // If parsing fails or any error occurs, return empty (safe fallback)
+    console.warn('Snippet selection failed, returning empty selection:', error)
+    return []
+  }
+}

package/src/snippets-to-bindings.ts

@@ -0,0 +1,135 @@
+import type { ToolExecutionContext } from '@tanstack/ai'
+import type { ToolBinding } from '@tanstack/ai-code-mode'
+import type { Snippet, SnippetStorage } from './types'
+
+interface SnippetsToBindingsOptions {
+  /**
+   * Snippets to convert to bindings
+   */
+  snippets: Array<Snippet>
+
+  /**
+   * Tool execution context for emitting custom events
+   */
+  context?: ToolExecutionContext
+
+  /**
+   * Function to execute snippet code in the sandbox
+   * The snippet code receives `input` as a variable
+   */
+  executeInSandbox: (code: string, input: unknown) => Promise<unknown>
+
+  /**
+   * Storage for updating execution stats
+   */
+  storage: SnippetStorage
+}
+
+/**
+ * Convert snippets to sandbox bindings with the snippet_ prefix.
+ * Snippets become callable functions inside the sandbox.
+ */
+export function snippetsToBindings({
+  snippets,
+  context,
+  executeInSandbox,
+  storage,
+}: SnippetsToBindingsOptions): Record<string, ToolBinding> {
+  const bindings: Record<string, ToolBinding> = {}
+
+  for (const snippet of snippets) {
+    const bindingName = `snippet_${snippet.name}`
+
+    bindings[bindingName] = {
+      name: bindingName,
+      description: snippet.description,
+      inputSchema: snippet.inputSchema,
+      outputSchema: snippet.outputSchema,
+      execute: async (input: unknown) => {
+        const startTime = Date.now()
+
+        // Emit snippet call event
+        context?.emitCustomEvent('code_mode:snippet_call', {
+          snippet: snippet.name,
+          input,
+          timestamp: startTime,
+        })
+
+        try {
+          // Wrap the snippet code to receive input as a variable
+          const wrappedCode = `
+            const input = ${JSON.stringify(input)};
+            ${snippet.code}
+          `
+
+          const result = await executeInSandbox(wrappedCode, input)
+          const duration = Date.now() - startTime
+
+          // Emit success event
+          context?.emitCustomEvent('code_mode:snippet_result', {
+            snippet: snippet.name,
+            result,
+            duration,
+            timestamp: Date.now(),
+          })
+
+          // Update stats (async, don't await to not block)
+          storage.updateStats(snippet.name, true).catch(() => {
+            // Silently ignore stats update failures
+          })
+
+          return result
+        } catch (error) {
+          const duration = Date.now() - startTime
+
+          // Emit error event
+          context?.emitCustomEvent('code_mode:snippet_error', {
+            snippet: snippet.name,
+            error: error instanceof Error ? error.message : String(error),
+            duration,
+            timestamp: Date.now(),
+          })
+
+          // Update stats (async, don't await)
+          storage.updateStats(snippet.name, false).catch(() => {
+            // Silently ignore stats update failures
+          })
+
+          throw error
+        }
+      },
+    }
+  }
+
+  return bindings
+}
+
+/**
+ * Create a simple binding record for snippets without full sandbox execution.
+ * This is used when snippets are being documented in the system prompt
+ * but not yet being executed.
+ */
+export function snippetsToSimpleBindings(
+  snippets: Array<Snippet>,
+): Record<string, ToolBinding> {
+  const bindings: Record<string, ToolBinding> = {}
+
+  for (const snippet of snippets) {
+    const bindingName = `snippet_${snippet.name}`
+
+    bindings[bindingName] = {
+      name: bindingName,
+      description: snippet.description,
+      inputSchema: snippet.inputSchema,
+      outputSchema: snippet.outputSchema,
+      execute: () =>
+        Promise.reject(
+          new Error(
+            `Snippet ${snippet.name} is not available for execution in this context`,
+          ),
+        ),
+    }
+  }
+
+  return bindings
+}