@boostecom/provider 0.0.1

package/docs/src/validation.ts

@@ -0,0 +1,360 @@
+import { z } from 'zod';
+import { existsSync } from 'fs';
+
+/**
+ * Validation schemas and utilities for Claude Code provider inputs.
+ * Uses Zod for type-safe validation following AI SDK patterns.
+ */
+
+// Helper for Zod v3/v4 compatibility
+// Use a simple z.any() for functions to work with both versions
+const loggerFunctionSchema = z.object({
+  debug: z.any().refine((val) => typeof val === 'function', {
+    message: 'debug must be a function',
+  }),
+  info: z.any().refine((val) => typeof val === 'function', {
+    message: 'info must be a function',
+  }),
+  warn: z.any().refine((val) => typeof val === 'function', {
+    message: 'warn must be a function',
+  }),
+  error: z.any().refine((val) => typeof val === 'function', {
+    message: 'error must be a function',
+  }),
+});
+
+/**
+ * Schema for validating Claude Code settings.
+ * Ensures all settings are within acceptable ranges and formats.
+ */
+export const claudeCodeSettingsSchema = z
+  .object({
+    pathToClaudeCodeExecutable: z.string().optional(),
+    customSystemPrompt: z.string().optional(),
+    appendSystemPrompt: z.string().optional(),
+    systemPrompt: z
+      .union([
+        z.string(),
+        z.object({
+          type: z.literal('preset'),
+          preset: z.literal('claude_code'),
+          append: z.string().optional(),
+        }),
+      ])
+      .optional(),
+    maxTurns: z.number().int().min(1).max(100).optional(),
+    maxThinkingTokens: z.number().int().positive().max(100000).optional(),
+    cwd: z
+      .string()
+      .refine(
+        (val) => {
+          // Skip directory validation in non-Node environments
+          if (typeof process === 'undefined' || !process.versions?.node) {
+            return true;
+          }
+          return !val || existsSync(val);
+        },
+        { message: 'Working directory must exist' }
+      )
+      .optional(),
+    executable: z.enum(['bun', 'deno', 'node']).optional(),
+    executableArgs: z.array(z.string()).optional(),
+    permissionMode: z
+      .enum(['default', 'acceptEdits', 'bypassPermissions', 'plan', 'delegate', 'dontAsk'])
+      .optional(),
+    permissionPromptToolName: z.string().optional(),
+    continue: z.boolean().optional(),
+    resume: z.string().optional(),
+    sessionId: z.string().optional(),
+    allowedTools: z.array(z.string()).optional(),
+    disallowedTools: z.array(z.string()).optional(),
+    betas: z.array(z.string()).optional(),
+    allowDangerouslySkipPermissions: z.boolean().optional(),
+    enableFileCheckpointing: z.boolean().optional(),
+    maxBudgetUsd: z.number().min(0).optional(),
+    plugins: z
+      .array(
+        z
+          .object({
+            type: z.string(),
+            path: z.string(),
+          })
+          .passthrough()
+      )
+      .optional(),
+    resumeSessionAt: z.string().optional(),
+    sandbox: z
+      .any()
+      .refine((val) => val === undefined || typeof val === 'object', {
+        message: 'sandbox must be an object',
+      })
+      .optional(),
+    tools: z
+      .union([
+        z.array(z.string()),
+        z.object({
+          type: z.literal('preset'),
+          preset: z.literal('claude_code'),
+        }),
+      ])
+      .optional(),
+    settingSources: z.array(z.enum(['user', 'project', 'local'])).optional(),
+    streamingInput: z.enum(['auto', 'always', 'off']).optional(),
+    // Hooks and tool-permission callback (permissive validation of shapes)
+    canUseTool: z
+      .any()
+      .refine((v) => v === undefined || typeof v === 'function', {
+        message: 'canUseTool must be a function',
+      })
+      .optional(),
+    hooks: z
+      .record(
+        z.string(),
+        z.array(
+          z.object({
+            matcher: z.string().optional(),
+            hooks: z.array(z.any()).nonempty(),
+          })
+        )
+      )
+      .optional(),
+    mcpServers: z
+      .record(
+        z.string(),
+        z.union([
+          // McpStdioServerConfig
+          z.object({
+            type: z.literal('stdio').optional(),
+            command: z.string(),
+            args: z.array(z.string()).optional(),
+            env: z.record(z.string(), z.string()).optional(),
+          }),
+          // McpSSEServerConfig
+          z.object({
+            type: z.literal('sse'),
+            url: z.string(),
+            headers: z.record(z.string(), z.string()).optional(),
+          }),
+          // McpHttpServerConfig
+          z.object({
+            type: z.literal('http'),
+            url: z.string(),
+            headers: z.record(z.string(), z.string()).optional(),
+          }),
+          // McpSdkServerConfig (in-process custom tools)
+          z.object({
+            type: z.literal('sdk'),
+            name: z.string(),
+            instance: z.any(),
+          }),
+        ])
+      )
+      .optional(),
+    verbose: z.boolean().optional(),
+    debug: z.boolean().optional(),
+    debugFile: z.string().optional(),
+    logger: z.union([z.literal(false), loggerFunctionSchema]).optional(),
+    env: z.record(z.string(), z.string().optional()).optional(),
+    additionalDirectories: z.array(z.string()).optional(),
+    agents: z
+      .record(
+        z.string(),
+        z
+          .object({
+            description: z.string(),
+            tools: z.array(z.string()).optional(),
+            disallowedTools: z.array(z.string()).optional(),
+            prompt: z.string(),
+            model: z.enum(['sonnet', 'opus', 'haiku', 'inherit']).optional(),
+            mcpServers: z
+              .array(
+                z.union([
+                  z.string(),
+                  z.record(z.string(), z.any()), // McpServerConfigForProcessTransport
+                ])
+              )
+              .optional(),
+            criticalSystemReminder_EXPERIMENTAL: z.string().optional(),
+          })
+          .passthrough()
+      )
+      .optional(),
+    includePartialMessages: z.boolean().optional(),
+    fallbackModel: z.string().optional(),
+    forkSession: z.boolean().optional(),
+    stderr: z
+      .any()
+      .refine((val) => val === undefined || typeof val === 'function', {
+        message: 'stderr must be a function',
+      })
+      .optional(),
+    strictMcpConfig: z.boolean().optional(),
+    extraArgs: z.record(z.string(), z.union([z.string(), z.null()])).optional(),
+    persistSession: z.boolean().optional(),
+    spawnClaudeCodeProcess: z
+      .any()
+      .refine((val) => val === undefined || typeof val === 'function', {
+        message: 'spawnClaudeCodeProcess must be a function',
+      })
+      .optional(),
+    sdkOptions: z.record(z.string(), z.any()).optional(),
+    maxToolResultSize: z.number().int().min(100).max(1000000).optional(),
+    // Callback invoked when Query object is created - for mid-stream injection via streamInput()
+    onQueryCreated: z
+      .any()
+      .refine((val) => val === undefined || typeof val === 'function', {
+        message: 'onQueryCreated must be a function',
+      })
+      .optional(),
+    onStreamStart: z
+      .any()
+      .refine((val) => val === undefined || typeof val === 'function', {
+        message: 'onStreamStart must be a function',
+      })
+      .optional(),
+  })
+  .strict();
+
+/**
+ * Validates a model ID and returns warnings if needed.
+ *
+ * @param modelId - The model ID to validate
+ * @returns Warning message if model is unknown, undefined otherwise
+ */
+export function validateModelId(modelId: string): string | undefined {
+  const knownModels = ['opus', 'sonnet', 'haiku'];
+
+  // Check for empty or whitespace-only
+  if (!modelId || modelId.trim() === '') {
+    throw new Error('Model ID cannot be empty');
+  }
+
+  // Warn about unknown models but allow them
+  if (!knownModels.includes(modelId)) {
+    return `Unknown model ID: '${modelId}'. Proceeding with custom model. Known models are: ${knownModels.join(', ')}`;
+  }
+
+  return undefined;
+}
+
+/**
+ * Validates Claude Code settings and returns validation results.
+ *
+ * @param settings - The settings object to validate
+ * @returns Object with validation results and any warnings
+ */
+export function validateSettings(settings: unknown): {
+  valid: boolean;
+  warnings: string[];
+  errors: string[];
+} {
+  const warnings: string[] = [];
+  const errors: string[] = [];
+
+  try {
+    // Parse with Zod schema
+    const result = claudeCodeSettingsSchema.safeParse(settings);
+
+    if (!result.success) {
+      // Extract user-friendly error messages
+      // Support both Zod v3 (errors) and v4 (issues)
+      const errorObject = result.error as {
+        errors?: Array<{ path: string[]; message: string }>;
+        issues?: Array<{ path: string[]; message: string }>;
+      };
+      const issues = errorObject.errors || errorObject.issues || [];
+      issues.forEach((err: { path: string[]; message: string }) => {
+        const path = err.path.join('.');
+        errors.push(`${path ? `${path}: ` : ''}${err.message}`);
+      });
+      return { valid: false, warnings, errors };
+    }
+
+    // Additional validation warnings
+    const validSettings = result.data;
+
+    // Warn about high turn limits
+    if (validSettings.maxTurns && validSettings.maxTurns > 20) {
+      warnings.push(
+        `High maxTurns value (${validSettings.maxTurns}) may lead to long-running conversations`
+      );
+    }
+
+    // Warn about very high thinking tokens
+    if (validSettings.maxThinkingTokens && validSettings.maxThinkingTokens > 50000) {
+      warnings.push(
+        `Very high maxThinkingTokens (${validSettings.maxThinkingTokens}) may increase response time`
+      );
+    }
+
+    // Check if both allowedTools and disallowedTools are specified
+    if (validSettings.allowedTools && validSettings.disallowedTools) {
+      warnings.push(
+        'Both allowedTools and disallowedTools are specified. Only allowedTools will be used.'
+      );
+    }
+
+    // Validate tool name format
+    const validateToolNames = (tools: string[], type: string) => {
+      tools.forEach((tool) => {
+        // Basic validation - tool names should be alphanumeric with optional specifiers
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*(\([^)]*\))?$/.test(tool) && !tool.startsWith('mcp__')) {
+          warnings.push(`Unusual ${type} tool name format: '${tool}'`);
+        }
+      });
+    };
+
+    if (validSettings.allowedTools) {
+      validateToolNames(validSettings.allowedTools, 'allowed');
+    }
+
+    if (validSettings.disallowedTools) {
+      validateToolNames(validSettings.disallowedTools, 'disallowed');
+    }
+
+    // Warn about Skills configuration issues
+    if (validSettings.allowedTools?.includes('Skill') && !validSettings.settingSources) {
+      warnings.push(
+        "allowedTools includes 'Skill' but settingSources is not set. Skills require settingSources (e.g., ['user', 'project']) to load skill definitions."
+      );
+    }
+
+    return { valid: true, warnings, errors };
+  } catch (error) {
+    errors.push(`Validation error: ${error instanceof Error ? error.message : String(error)}`);
+    return { valid: false, warnings, errors };
+  }
+}
+
+/**
+ * Validates prompt length and format.
+ *
+ * @param prompt - The prompt to validate
+ * @returns Warning message if prompt might cause issues
+ */
+export function validatePrompt(prompt: string): string | undefined {
+  // Very long prompts might cause issues
+  const MAX_PROMPT_LENGTH = 100000; // ~25k tokens
+
+  if (prompt.length > MAX_PROMPT_LENGTH) {
+    return `Very long prompt (${prompt.length} characters) may cause performance issues or timeouts`;
+  }
+
+  return undefined;
+}
+
+/**
+ * Validates session ID format.
+ *
+ * @param sessionId - The session ID to validate
+ * @returns Warning message if format is unusual
+ */
+export function validateSessionId(sessionId: string): string | undefined {
+  // Session IDs from Claude Code are typically UUID-like
+  // But we don't want to be too strict as format might change
+  if (sessionId && !/^[a-zA-Z0-9-_]+$/.test(sessionId)) {
+    return `Unusual session ID format. This may cause issues with session resumption.`;
+  }
+
+  return undefined;
+}

package/package.json

@@ -0,0 +1,124 @@
+{
+  "name": "@boostecom/provider",
+  "version": "0.0.1",
+  "description": "AI SDK v6 provider for Claude via Claude Agent SDK (use Pro/Max subscription)",
+  "keywords": [
+    "ai-sdk",
+    "claude-agent-sdk",
+    "anthropic",
+    "cli",
+    "language-model",
+    "llm"
+  ],
+  "homepage": "https://github.com/BoostEcom/ThemeCopilotAI",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BoostEcom/ThemeCopilotAI.git"
+  },
+  "bugs": {
+    "url": "https://github.com/BoostEcom/ThemeCopilotAI/issues"
+  },
+  "license": "MIT",
+  "author": "Christopher Lasgi <dev@boostecom.dev>",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "docs/**/*",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "build:lib": "tsup",
+    "build:docs": "next build",
+    "clean": "rm -rf dist",
+    "dev": "next dev",
+    "dev:lib": "tsup --watch",
+    "start": "next start",
+    "lint": "eslint src",
+    "lint:all": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "ci": "npm run typecheck && npm run lint:all && npm run test",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run clean && npm run build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:edge": "vitest run --project=edge",
+    "test:node": "vitest run --project=node",
+    "test:watch": "vitest",
+    "test:integration": "npm run build && npx tsx examples/integration-test.ts",
+    "typecheck": "tsc --noEmit",
+    "example:basic": "npm run build && npx tsx examples/basic-usage.ts",
+    "example:streaming": "npm run build && npx tsx examples/streaming.ts",
+    "example:conversation": "npm run build && npx tsx examples/conversation-history.ts",
+    "example:config": "npm run build && npx tsx examples/custom-config.ts",
+    "example:object": "npm run build && npx tsx examples/generate-object.ts",
+    "example:object:constraints": "npm run build && npx tsx examples/generate-object-constraints.ts",
+    "example:tools": "npm run build && npx tsx examples/tool-management.ts",
+    "example:timeout": "npm run build && npx tsx examples/long-running-tasks.ts",
+    "example:zod4": "npm run build && npx tsx examples/zod4-compatibility-test.ts",
+    "example:structured-repro": "npx tsx examples/structured-output-repro.ts",
+    "example:agent-teams": "npm run build && npx tsx examples/agent-teams.ts",
+    "example:skills-discovery": "npm run build && npx tsx examples/skills-discovery.ts",
+    "example:all": "npm run build && npm run example:basic && npm run example:streaming && npm run example:conversation && npm run example:config && npm run example:object && npm run example:object:constraints && npm run example:tools && npm run example:timeout"
+  },
+  "dependencies": {
+    "@ai-sdk/provider": "^3.0.0",
+    "@ai-sdk/provider-utils": "^4.0.1",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.33"
+  },
+  "devDependencies": {
+    "@edge-runtime/vm": "5.0.0",
+    "@eslint/js": "9.28.0",
+    "@tailwindcss/postcss": "^4.1.18",
+    "@tailwindcss/typography": "^0.5.19",
+    "@types/node": "^20.19.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@typescript-eslint/eslint-plugin": "8.34.0",
+    "@typescript-eslint/parser": "8.34.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "ai": "^6.0.3",
+    "autoprefixer": "^10.4.20",
+    "clsx": "^2.1.1",
+    "eslint": "9.28.0",
+    "globals": "16.2.0",
+    "lucide-react": "^0.468.0",
+    "next": "^16.0.0",
+    "postcss": "^8.4.49",
+    "prettier": "^3.6.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-markdown": "^9.0.1",
+    "remark-gfm": "^4.0.0",
+    "tailwind-merge": "^3.0.0",
+    "tailwindcss": "^4.0.0",
+    "tailwindcss-animate": "^1.0.7",
+    "tsup": "8.5.0",
+    "typescript": "5.6.3",
+    "vitest": "3.2.4",
+    "zod": "^4.1.12"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}