@tanstack/ai-code-mode-snippets 0.3.14

package/src/snippets-to-tools.ts

@@ -0,0 +1,325 @@
+import { toolDefinition } from '@tanstack/ai'
+import {
+  createEventAwareBindings,
+  stripTypeScript,
+  toolsToBindings,
+} from '@tanstack/ai-code-mode'
+import { z } from 'zod'
+import type {
+  SchemaInput,
+  ServerTool,
+  ToolExecutionContext,
+} from '@tanstack/ai'
+import type {
+  CodeModeTool,
+  IsolateDriver,
+  ToolBinding,
+} from '@tanstack/ai-code-mode'
+import type { Snippet, SnippetStorage } from './types'
+
+/**
+ * Options for converting a single snippet to a tool
+ */
+export interface SnippetToToolOptions {
+  /**
+   * The snippet to convert
+   */
+  snippet: Snippet
+
+  /**
+   * Isolate driver for executing snippet code
+   */
+  driver: IsolateDriver
+
+  /**
+   * Pre-computed bindings for external_* functions
+   */
+  bindings: Record<string, ToolBinding>
+
+  /**
+   * Storage for updating execution stats
+   */
+  storage: SnippetStorage
+
+  /**
+   * Timeout for snippet execution in ms
+   * @default 30000
+   */
+  timeout?: number
+
+  /**
+   * Memory limit in bytes
+   * @default 128
+   */
+  memoryLimit?: number
+}
+
+interface SnippetsToToolsOptions {
+  /**
+   * Snippets to convert to tools
+   */
+  snippets: Array<Snippet>
+
+  /**
+   * Isolate driver for executing snippet code
+   */
+  driver: IsolateDriver
+
+  /**
+   * Original tools that become external_* bindings
+   * (so snippets can call external_* functions)
+   */
+  tools: Array<CodeModeTool>
+
+  /**
+   * Storage for updating execution stats
+   */
+  storage: SnippetStorage
+
+  /**
+   * Timeout for snippet execution in ms
+   * @default 30000
+   */
+  timeout?: number
+
+  /**
+   * Memory limit in bytes
+   * @default 128
+   */
+  memoryLimit?: number
+}
+
+/**
+ * Convert JSON Schema to Zod schema.
+ * This is a simplified converter that handles common cases.
+ */
+function jsonSchemaToZod(schema: Record<string, unknown>): z.ZodType {
+  const type = schema.type as string
+
+  if (type === 'string') {
+    let zodString = z.string()
+    if (schema.description) {
+      zodString = zodString.describe(schema.description as string)
+    }
+    return zodString
+  }
+  if (type === 'number' || type === 'integer') {
+    let zodNum = z.number()
+    if (schema.description) {
+      zodNum = zodNum.describe(schema.description as string)
+    }
+    return zodNum
+  }
+  if (type === 'boolean') {
+    let zodBool = z.boolean()
+    if (schema.description) {
+      zodBool = zodBool.describe(schema.description as string)
+    }
+    return zodBool
+  }
+  if (type === 'array') {
+    const items = schema.items as Record<string, unknown> | undefined
+    if (items) {
+      return z.array(jsonSchemaToZod(items))
+    }
+    return z.array(z.unknown())
+  }
+  if (type === 'object') {
+    const properties = schema.properties as
+      | Record<string, Record<string, unknown>>
+      | undefined
+    const required = (schema.required as Array<string> | undefined) ?? []
+
+    if (properties) {
+      const shape: Record<string, z.ZodType> = {}
+      for (const [key, propSchema] of Object.entries(properties)) {
+        let zodProp = jsonSchemaToZod(propSchema)
+        if (!required.includes(key)) {
+          zodProp = zodProp.optional()
+        }
+        shape[key] = zodProp
+      }
+      return z.object(shape)
+    }
+    return z.record(z.string(), z.unknown())
+  }
+
+  // Fallback
+  return z.unknown()
+}
+
+/**
+ * Convert a single snippet to a ServerTool that the LLM can call directly.
+ * The snippet executes its code in the sandbox with access to external_* bindings.
+ */
+export function snippetToTool({
+  snippet,
+  driver,
+  bindings,
+  storage,
+  timeout = 30000,
+  memoryLimit = 128,
+}: SnippetToToolOptions): ServerTool<SchemaInput, SchemaInput, string> {
+  // Generate input and output schemas from JSON Schema
+  const inputSchema = jsonSchemaToZod(snippet.inputSchema)
+  const outputSchema = jsonSchemaToZod(snippet.outputSchema)
+
+  return toolDefinition({
+    name: snippet.name,
+    description: `[SNIPPET] ${snippet.description}`,
+    inputSchema,
+    outputSchema,
+  }).server(async (input: unknown, context?: ToolExecutionContext) => {
+    const startTime = Date.now()
+    const emitCustomEvent = context?.emitCustomEvent || (() => {})
+
+    // Emit snippet call event
+    emitCustomEvent('code_mode:snippet_call', {
+      snippet: snippet.name,
+      input,
+      timestamp: startTime,
+    })
+
+    let isolateContext = null
+
+    try {
+      console.log(
+        `[Snippet:${snippet.name}] Starting execution with input:`,
+        JSON.stringify(input).substring(0, 200),
+      )
+
+      // Wrap the snippet code to receive input as a variable
+      const wrappedCode = `
+          const input = ${JSON.stringify(input)};
+          ${snippet.code}
+        `
+      console.log(
+        `[Snippet:${snippet.name}] Wrapped code (first 500 chars):`,
+        wrappedCode.substring(0, 500),
+      )
+
+      // Strip TypeScript to JavaScript
+      const strippedCode = await stripTypeScript(wrappedCode)
+      console.log(
+        `[Snippet:${snippet.name}] Stripped code (first 500 chars):`,
+        strippedCode.substring(0, 500),
+      )
+
+      // Create event-aware bindings
+      const eventAwareBindings = createEventAwareBindings(
+        bindings,
+        emitCustomEvent,
+      )
+      console.log(
+        `[Snippet:${snippet.name}] Event-aware bindings:`,
+        Object.keys(eventAwareBindings),
+      )
+
+      // Create sandbox context
+      console.log(`[Snippet:${snippet.name}] Creating sandbox context...`)
+      isolateContext = await driver.createContext({
+        bindings: eventAwareBindings,
+        timeout,
+        memoryLimit,
+      })
+      console.log(`[Snippet:${snippet.name}] Sandbox context created`)
+
+      // Execute the code
+      console.log(`[Snippet:${snippet.name}] Executing code...`)
+      const executionResult = await isolateContext.execute(strippedCode)
+      console.log(`[Snippet:${snippet.name}] Execution result:`, {
+        success: executionResult.success,
+        hasValue: 'value' in executionResult,
+        error: executionResult.error,
+        logs: executionResult.logs,
+      })
+
+      const duration = Date.now() - startTime
+
+      if (!executionResult.success) {
+        console.error(
+          `[Snippet:${snippet.name}] Execution failed:`,
+          executionResult.error,
+        )
+        throw new Error(
+          executionResult.error?.message || 'Snippet execution failed',
+        )
+      }
+
+      // Emit success event
+      emitCustomEvent('code_mode:snippet_result', {
+        snippet: snippet.name,
+        result: executionResult.value,
+        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 executionResult.value
+    } catch (error) {
+      const duration = Date.now() - startTime
+      console.error(`[Snippet:${snippet.name}] CAUGHT ERROR:`, {
+        message: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+        duration,
+      })
+
+      // Emit error event
+      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
+    } finally {
+      if (isolateContext) {
+        await isolateContext.dispose()
+      }
+    }
+  })
+}
+
+/**
+ * Convert multiple snippets to ServerTools that the LLM can call directly.
+ * Snippets become real tools that execute their code in the sandbox.
+ */
+export function snippetsToTools({
+  snippets,
+  driver,
+  tools,
+  storage,
+  timeout = 30000,
+  memoryLimit = 128,
+}: SnippetsToToolsOptions): Array<
+  ServerTool<SchemaInput, SchemaInput, string>
+> {
+  // Pre-compute bindings from tools (these are shared across all snippet executions)
+  console.log(
+    '[SnippetsToTools] Creating bindings from tools:',
+    tools.map((t) => t.name),
+  )
+  const bindings = toolsToBindings(tools, 'external_')
+  console.log('[SnippetsToTools] Created bindings:', Object.keys(bindings))
+
+  return snippets.map((snippet) =>
+    snippetToTool({
+      snippet,
+      driver,
+      bindings,
+      storage,
+      timeout,
+      memoryLimit,
+    }),
+  )
+}

package/src/storage/file-storage.ts

@@ -0,0 +1,275 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { existsSync } from 'node:fs'
+import { createDefaultTrustStrategy } from '../trust-strategies'
+import type {
+  Snippet,
+  SnippetIndexEntry,
+  SnippetSearchOptions,
+  SnippetStorage,
+} from '../types'
+import type { TrustStrategy } from '../trust-strategies'
+
+export interface FileSnippetStorageOptions {
+  /**
+   * Directory path for storing snippets
+   */
+  directory: string
+
+  /**
+   * Trust strategy for determining snippet trust levels
+   * @default createDefaultTrustStrategy()
+   */
+  trustStrategy?: TrustStrategy
+}
+
+/**
+ * File-system based snippet storage
+ *
+ * Directory structure:
+ *   .snippets/
+ *     _index.json          # Fast catalog loading
+ *     fetch_github_stats/
+ *       meta.json          # Metadata (description, schemas, hints, stats)
+ *       code.ts            # The actual TypeScript code
+ *     deploy_to_prod/
+ *       meta.json
+ *       code.ts
+ */
+export function createFileSnippetStorage(
+  directoryOrOptions: string | FileSnippetStorageOptions,
+): SnippetStorage {
+  const options =
+    typeof directoryOrOptions === 'string'
+      ? { directory: directoryOrOptions }
+      : directoryOrOptions
+
+  const { directory, trustStrategy = createDefaultTrustStrategy() } = options
+  const indexPath = join(directory, '_index.json')
+
+  console.log('[FileSnippetStorage] Initialized with directory:', directory)
+
+  // Snippet names are used both as on-disk directory segments and as
+  // `snippet_<name>` sandbox tool names, so they must be a single safe
+  // identifier segment. Rejecting anything else keeps an LLM-supplied name
+  // (e.g. `../../etc`) from escaping `directory` during read/write/delete.
+  const SAFE_SNIPPET_NAME = /^[A-Za-z0-9_-]+$/
+
+  function isSafeSnippetName(name: string): boolean {
+    return typeof name === 'string' && SAFE_SNIPPET_NAME.test(name)
+  }
+
+  function assertSafeSnippetName(name: string): void {
+    if (!isSafeSnippetName(name)) {
+      throw new Error(
+        `Invalid snippet name ${JSON.stringify(
+          name,
+        )}: names must match /^[A-Za-z0-9_-]+$/ (no path separators or traversal).`,
+      )
+    }
+  }
+
+  async function ensureDirectory(): Promise<void> {
+    if (!existsSync(directory)) {
+      console.log('[FileSnippetStorage] Creating directory:', directory)
+      await mkdir(directory, { recursive: true })
+    }
+  }
+
+  async function loadIndex(): Promise<Array<SnippetIndexEntry>> {
+    await ensureDirectory()
+
+    if (!existsSync(indexPath)) {
+      return []
+    }
+
+    const content = await readFile(indexPath, 'utf-8')
+    return JSON.parse(content) as Array<SnippetIndexEntry>
+  }
+
+  async function loadAll(): Promise<Array<Snippet>> {
+    const index = await loadIndex()
+    const snippets: Array<Snippet> = []
+
+    for (const entry of index) {
+      const snippet = await get(entry.name)
+      if (snippet) {
+        snippets.push(snippet)
+      }
+    }
+
+    return snippets
+  }
+
+  async function saveIndex(index: Array<SnippetIndexEntry>): Promise<void> {
+    await writeFile(indexPath, JSON.stringify(index, null, 2))
+  }
+
+  async function get(name: string): Promise<Snippet | null> {
+    // Treat an unsafe name as "not found" rather than reading outside `directory`.
+    if (!isSafeSnippetName(name)) {
+      return null
+    }
+
+    const snippetDir = join(directory, name)
+    const metaPath = join(snippetDir, 'meta.json')
+    const codePath = join(snippetDir, 'code.ts')
+
+    if (!existsSync(metaPath)) {
+      return null
+    }
+
+    const [metaContent, code] = await Promise.all([
+      readFile(metaPath, 'utf-8'),
+      readFile(codePath, 'utf-8'),
+    ])
+
+    const meta = JSON.parse(metaContent) as Omit<Snippet, 'code'>
+    return { ...meta, code }
+  }
+
+  async function save(
+    snippet: Omit<Snippet, 'createdAt' | 'updatedAt'>,
+  ): Promise<Snippet> {
+    assertSafeSnippetName(snippet.name)
+    await ensureDirectory()
+
+    const snippetDir = join(directory, snippet.name)
+    const metaPath = join(snippetDir, 'meta.json')
+    const codePath = join(snippetDir, 'code.ts')
+
+    const now = new Date().toISOString()
+    const existing = await get(snippet.name)
+
+    const fullSnippet: Snippet = {
+      ...snippet,
+      createdAt: existing?.createdAt ?? now,
+      updatedAt: now,
+    }
+
+    // Separate code from metadata
+    const { code, ...meta } = fullSnippet
+
+    // Write snippet files
+    await mkdir(snippetDir, { recursive: true })
+    await Promise.all([
+      writeFile(metaPath, JSON.stringify(meta, null, 2)),
+      writeFile(codePath, code),
+    ])
+
+    // Update index
+    const index = await loadIndex()
+    const indexEntry: SnippetIndexEntry = {
+      id: fullSnippet.id,
+      name: fullSnippet.name,
+      description: fullSnippet.description,
+      usageHints: fullSnippet.usageHints,
+      trustLevel: fullSnippet.trustLevel,
+    }
+
+    const existingIdx = index.findIndex((s) => s.name === snippet.name)
+    if (existingIdx >= 0) {
+      index[existingIdx] = indexEntry
+    } else {
+      index.push(indexEntry)
+    }
+    await saveIndex(index)
+
+    return fullSnippet
+  }
+
+  async function deleteSnippet(name: string): Promise<boolean> {
+    assertSafeSnippetName(name)
+
+    const snippetDir = join(directory, name)
+
+    if (!existsSync(snippetDir)) {
+      return false
+    }
+
+    await rm(snippetDir, { recursive: true })
+
+    // Update index
+    const index = await loadIndex()
+    const filtered = index.filter((s) => s.name !== name)
+    await saveIndex(filtered)
+
+    return true
+  }
+
+  async function search(
+    query: string,
+    searchOptions: SnippetSearchOptions = {},
+  ): Promise<Array<SnippetIndexEntry>> {
+    const { limit = 5 } = searchOptions
+    const index = await loadIndex()
+
+    // Simple text matching - can be replaced with embeddings
+    const queryLower = query.toLowerCase()
+    const terms = queryLower.split(/\s+/)
+
+    const scored = index.map((snippet) => {
+      let score = 0
+      const searchText = [
+        snippet.name,
+        snippet.description,
+        ...snippet.usageHints,
+      ]
+        .join(' ')
+        .toLowerCase()
+
+      for (const term of terms) {
+        if (searchText.includes(term)) {
+          score += 1
+        }
+        // Boost exact name matches
+        if (snippet.name.toLowerCase().includes(term)) {
+          score += 2
+        }
+      }
+
+      return { snippet, score }
+    })
+
+    return scored
+      .filter((s) => s.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit)
+      .map((s) => s.snippet)
+  }
+
+  async function updateStats(name: string, success: boolean): Promise<void> {
+    const snippet = await get(name)
+    if (!snippet) return
+
+    const { executions, successRate } = snippet.stats
+    const newExecutions = executions + 1
+    const newSuccessRate =
+      (successRate * executions + (success ? 1 : 0)) / newExecutions
+
+    const newStats = { executions: newExecutions, successRate: newSuccessRate }
+
+    // Use trust strategy to calculate new trust level
+    const newTrustLevel = trustStrategy.calculateTrustLevel(
+      snippet.trustLevel,
+      newStats,
+    )
+
+    await save({
+      ...snippet,
+      stats: newStats,
+      trustLevel: newTrustLevel,
+    })
+  }
+
+  return {
+    loadIndex,
+    loadAll,
+    get,
+    save,
+    delete: deleteSnippet,
+    search,
+    updateStats,
+    trustStrategy,
+  }
+}

package/src/storage/index.ts

@@ -0,0 +1,6 @@
+// Storage implementations
+export { createFileSnippetStorage } from './file-storage'
+export { createMemorySnippetStorage } from './memory-storage'
+
+// Re-export types
+export type { SnippetStorage, Snippet, SnippetIndexEntry } from '../types'