@boostecom/provider 0.0.1

package/docs/content/troubleshooting.mdx

@@ -0,0 +1,588 @@
+---
+title: Dépannage
+description: Solutions aux problèmes courants avec le provider Claude Code
+---
+
+# Dépannage
+
+Cette page répertorie les problèmes courants et leurs solutions.
+
+## Problèmes d'installation
+
+### Le CLI n'est pas trouvé
+
+**Symptôme** : `command not found: claude` ou `ENOENT`
+
+**Cause** : Le CLI Claude Code n'est pas installé ou pas dans le PATH
+
+**Solution** :
+
+```bash
+# Vérifier l'installation
+which claude
+
+# Si non trouvé, installer
+npm install -g @anthropic-ai/claude-code
+
+# Vérifier à nouveau
+claude --version
+```
+
+Si le problème persiste :
+
+```bash
+# Vérifier le répertoire global npm
+npm config get prefix
+
+# Ajouter au PATH si nécessaire (dans ~/.bashrc ou ~/.zshrc)
+export PATH="$PATH:$(npm config get prefix)/bin"
+
+# Recharger le shell
+source ~/.bashrc  # ou ~/.zshrc
+```
+
+### Erreur d'authentification
+
+**Symptôme** : `Authentication failed` ou `Unauthorized`
+
+**Solution 1** : Réauthentification
+
+```bash
+# Supprimer les identifiants existants
+rm -rf ~/.claude
+
+# Se reconnecter
+claude login
+```
+
+**Solution 2** : Vérifier les permissions
+
+```bash
+# Vérifier les permissions du répertoire
+ls -la ~/.claude
+
+# Corriger si nécessaire
+chmod 700 ~/.claude
+chmod 600 ~/.claude/*
+```
+
+### Incompatibilité de version Zod
+
+**Symptôme** : Erreurs TypeScript avec les types Zod
+
+**Cause** : Version 3.2.0+ nécessite Zod 4
+
+**Solution** :
+
+```bash
+# Vérifier la version de Zod
+npm list zod
+
+# Mettre à jour vers Zod 4
+npm install zod@^4.0.0
+
+# Ou downgrader le provider si Zod 3 requis
+npm install @boostecom/provider@3.1.x
+```
+
+## Problèmes d'exécution
+
+### Timeout lors de la génération
+
+**Symptôme** : La requête expire après 30 secondes
+
+**Solution** : Augmenter le timeout
+
+```typescript
+const controller = new AbortController();
+const timeoutId = setTimeout(() => controller.abort(), 300000); // 5 minutes
+
+try {
+  const { text } = await generateText({
+    model: claudeCode('opus'),
+    prompt: 'Tâche longue...',
+    abortSignal: controller.signal,
+  });
+  clearTimeout(timeoutId);
+} catch (error: any) {
+  if (error.name === 'AbortError') {
+    console.error('Timeout dépassé');
+  }
+}
+```
+
+### Erreur "Model not found"
+
+**Symptôme** : `Model 'xyz' not found`
+
+**Cause** : Nom de modèle invalide
+
+**Solution** : Utiliser un nom de modèle valide
+
+```typescript
+// ❌ Incorrect
+const model = claudeCode('gpt-4'); // Mauvais provider
+
+// ✅ Correct
+const model = claudeCode('opus');
+const model = claudeCode('sonnet');
+const model = claudeCode('haiku');
+
+// ✅ Ou identifiant complet
+const model = claudeCode('claude-opus-4-5');
+```
+
+### "No such file or directory" avec cwd
+
+**Symptôme** : Erreur lors de l'utilisation de `cwd`
+
+**Solution** : Utiliser un chemin absolu
+
+```typescript
+import { resolve } from 'path';
+
+// ❌ Chemin relatif (peut échouer)
+const model = claudeCode('sonnet', {
+  cwd: './mon-projet',
+});
+
+// ✅ Chemin absolu
+const model = claudeCode('sonnet', {
+  cwd: resolve(__dirname, './mon-projet'),
+});
+```
+
+## Problèmes avec structured outputs
+
+### Le CLI retourne du texte au lieu de JSON
+
+**Symptôme** : La réponse est en prose malgré `generateObject()`
+
+**Cause** : Le schéma contient des contraintes non supportées
+
+**Contraintes problématiques** :
+- `.email()`, `.url()`, `.uuid()`, `.datetime()`
+- Regex avec lookaheads/lookbehinds
+- `format` constraints trop strictes
+
+**Solution** : Simplifier le schéma
+
+```typescript
+// ❌ Problématique
+const schema = z.object({
+  email: z.string().email(), // Cause fallback
+  url: z.string().url(),
+  code: z.string().regex(/^(?=.*[A-Z])(?=.*[0-9]).{8,}$/), // Lookahead
+});
+
+// ✅ Solution
+const schema = z.object({
+  email: z.string().describe('Adresse email (ex: user@example.com)'),
+  url: z.string().describe('URL (ex: https://example.com)'),
+  code: z.string().min(8).describe('Code avec maj et chiffres'),
+});
+
+// Valider côté client si nécessaire
+const result = await generateObject({ model, schema, prompt });
+const isValidEmail = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(result.object.email);
+```
+
+### Schéma trop complexe
+
+**Symptôme** : Génération lente ou erreurs de validation
+
+**Solution** : Décomposer en étapes
+
+```typescript
+// ❌ Schéma massif
+const hugeSchema = z.object({
+  // 50+ champs...
+});
+
+// ✅ Décomposer
+const step1Schema = z.object({ /* 10 champs */ });
+const step2Schema = z.object({ /* 10 champs */ });
+
+const result1 = await generateObject({ model, schema: step1Schema, prompt: '...' });
+const result2 = await generateObject({ model, schema: step2Schema, prompt: '...' });
+
+const combined = { ...result1.object, ...result2.object };
+```
+
+## Problèmes avec les outils
+
+### Skills non chargées
+
+**Symptôme** : Les skills ne sont pas disponibles
+
+**Solution** : Vérifier la configuration
+
+```typescript
+// ❌ Configuration incomplète
+const model = claudeCode('sonnet', {
+  allowedTools: ['Skill'], // 'Skill' présent mais...
+  // Manque: settingSources
+});
+
+// ✅ Configuration complète
+const model = claudeCode('sonnet', {
+  settingSources: ['user', 'project'], // Requis
+  allowedTools: ['Skill'], // Requis
+});
+```
+
+Vérifier l'emplacement des skills :
+
+```bash
+# Skills globales
+ls -la ~/.claude/skills/
+
+# Skills projet
+ls -la .claude/skills/
+
+# Chaque skill doit avoir un SKILL.md
+cat .claude/skills/ma-skill/SKILL.md
+```
+
+### Outil refusé malgré allowedTools
+
+**Symptôme** : Claude dit qu'il ne peut pas utiliser un outil autorisé
+
+**Solution** : Vérifier les patterns
+
+```typescript
+// ❌ Pattern trop restrictif
+const model = claudeCode('sonnet', {
+  allowedTools: ['Bash(git log:*)'], // Seulement git log
+});
+
+// ✅ Pattern plus large
+const model = claudeCode('sonnet', {
+  allowedTools: ['Bash(git:*)'], // Toutes commandes git
+});
+
+// ✅ Ou tous les outils Bash
+const model = claudeCode('sonnet', {
+  allowedTools: ['Bash'],
+});
+```
+
+### canUseTool ne fonctionne pas
+
+**Symptôme** : Le callback `canUseTool` n'est jamais appelé
+
+**Cause** : `streamingInput` non activé
+
+**Solution** :
+
+```typescript
+// ❌ Manque streamingInput
+const model = claudeCode('sonnet', {
+  canUseTool: async (tool) => true,
+});
+
+// ✅ Activer streamingInput
+const model = claudeCode('sonnet', {
+  streamingInput: 'always', // Requis
+  canUseTool: async (tool) => true,
+});
+```
+
+## Problèmes avec les images
+
+### Images non traitées
+
+**Symptôme** : Les images sont ignorées
+
+**Cause** : `streamingInput` non activé
+
+**Solution** :
+
+```typescript
+const result = streamText({
+  model: claudeCode('sonnet', {
+    streamingInput: 'always', // Requis pour images
+  }),
+  messages: [
+    {
+      role: 'user',
+      content: [
+        { type: 'text', text: 'Décris cette image' },
+        { type: 'image', image: dataUrl },
+      ],
+    },
+  ],
+});
+```
+
+### "Invalid image format"
+
+**Symptôme** : Erreur de format d'image
+
+**Cause** : Format non supporté ou data URL invalide
+
+**Solution** :
+
+```typescript
+import { readFileSync } from 'fs';
+
+// ✅ Formats supportés: PNG, JPEG, GIF, WebP
+const imageBuffer = readFileSync('/chemin/vers/image.png');
+const base64 = imageBuffer.toString('base64');
+const dataUrl = `data:image/png;base64,${base64}`;
+
+// ❌ URLs distantes non supportées
+const badUrl = 'https://example.com/image.png';
+
+// ❌ Chemins de fichier non supportés
+const badPath = '/chemin/vers/image.png';
+```
+
+### Image trop grande
+
+**Symptôme** : Erreur ou traitement très lent
+
+**Solution** : Redimensionner l'image
+
+```typescript
+import sharp from 'sharp';
+
+// Redimensionner avant envoi
+const resized = await sharp('/chemin/vers/image.jpg')
+  .resize(1024, 1024, { fit: 'inside' })
+  .toBuffer();
+
+const base64 = resized.toString('base64');
+const dataUrl = `data:image/jpeg;base64,${base64}`;
+```
+
+## Problèmes de session
+
+### Session perdue entre requêtes
+
+**Symptôme** : Le contexte n'est pas maintenu
+
+**Cause** : Nouvelle session à chaque requête
+
+**Solution** : Utiliser l'historique de messages
+
+```typescript
+import type { CoreMessage } from 'ai';
+
+// Maintenir l'historique
+const messages: CoreMessage[] = [];
+
+// Requête 1
+messages.push({ role: 'user', content: 'Bonjour' });
+const result1 = await generateText({ model, messages });
+messages.push({ role: 'assistant', content: result1.text });
+
+// Requête 2 (avec contexte)
+messages.push({ role: 'user', content: 'Comment m\'appelles-tu ?' });
+const result2 = await generateText({ model, messages });
+```
+
+### "Cannot resume session"
+
+**Symptôme** : Impossible de reprendre une session
+
+**Solution** : Vérifier l'ID de session
+
+```bash
+# Lister les sessions disponibles
+ls -la ~/.claude/projects/
+
+# Vérifier la session spécifique
+cat ~/.claude/projects/SESSION_ID/metadata.json
+```
+
+```typescript
+// Utiliser le bon ID
+const model = claudeCode('sonnet', {
+  resume: 'SESSION_ID_VALIDE', // Depuis metadata.json
+});
+```
+
+## Problèmes de performance
+
+### Génération trop lente
+
+**Solutions** :
+
+1. **Utiliser un modèle plus rapide**
+
+```typescript
+// ❌ Opus pour tâche simple
+const slow = claudeCode('opus');
+
+// ✅ Haiku pour rapidité
+const fast = claudeCode('haiku');
+```
+
+2. **Limiter les outils**
+
+```typescript
+// Moins d'outils = plus rapide
+const model = claudeCode('sonnet', {
+  allowedTools: ['Read'], // Seulement ce qui est nécessaire
+});
+```
+
+3. **Réduire maxTurns**
+
+```typescript
+const model = claudeCode('sonnet', {
+  maxTurns: 3, // Limiter les allers-retours
+});
+```
+
+### Consommation mémoire élevée
+
+**Solution** : Streaming et nettoyage
+
+```typescript
+const result = streamText({ model, prompt });
+
+// Traiter chunk par chunk
+for await (const chunk of result.textStream) {
+  process.stdout.write(chunk);
+  // Le chunk est garbage collected après utilisation
+}
+
+// Pas besoin de stocker toute la réponse en mémoire
+```
+
+## Problèmes en environnement Docker
+
+### CLI non trouvé dans conteneur
+
+**Solution** : Installer dans l'image
+
+```dockerfile
+FROM node:18-alpine
+
+# Installer le CLI
+RUN npm install -g @anthropic-ai/claude-code
+
+# Copier le code
+WORKDIR /app
+COPY . .
+RUN npm install
+
+CMD ["node", "index.js"]
+```
+
+### Permissions dans Docker
+
+**Solution** : Créer le répertoire avec bonnes permissions
+
+```dockerfile
+FROM node:18-alpine
+
+RUN npm install -g @anthropic-ai/claude-code
+
+# Créer le répertoire Claude avec permissions
+RUN mkdir -p /root/.claude && chmod 700 /root/.claude
+
+WORKDIR /app
+COPY . .
+RUN npm install
+
+CMD ["node", "index.js"]
+```
+
+### Authentification en CI/CD
+
+**Solution** : Utiliser des secrets
+
+```yaml
+# .github/workflows/test.yml
+- name: Setup Claude Auth
+  run: |
+    mkdir -p ~/.claude
+    echo "${{ secrets.CLAUDE_AUTH }}" > ~/.claude/auth.json
+    chmod 600 ~/.claude/auth.json
+```
+
+## Logs et debugging
+
+### Activer les logs détaillés
+
+```typescript
+const model = claudeCode('sonnet', {
+  verbose: true, // Tous les logs
+  debug: true,   // Logs SDK
+  debugFile: '/tmp/claude-debug.log', // Fichier de logs
+});
+```
+
+### Logger personnalisé pour debugging
+
+```typescript
+import type { Logger } from '@boostecom/provider';
+
+const debugLogger: Logger = {
+  debug: (msg) => {
+    console.log(`[${new Date().toISOString()}] DEBUG:`, msg);
+    fs.appendFileSync('/tmp/debug.log', `${msg}\n`);
+  },
+  info: (msg) => console.log(`[INFO]`, msg),
+  warn: (msg) => console.warn(`[WARN]`, msg),
+  error: (msg) => {
+    console.error(`[ERROR]`, msg);
+    // Envoyer à un service de monitoring
+    sendToSentry(msg);
+  },
+};
+
+const model = claudeCode('sonnet', {
+  verbose: true,
+  logger: debugLogger,
+});
+```
+
+## Obtenir de l'aide
+
+Si votre problème n'est pas listé ici :
+
+1. **Vérifier les exemples** : [Exemples](/docs/examples)
+2. **Consulter l'API** : [API Reference](/docs/api)
+3. **Issues GitHub** : [Ouvrir une issue](https://github.com/BoostEcom/ThemeCopilotAI/issues)
+4. **Discord Vercel** : [Communauté AI SDK](https://vercel.com/discord)
+
+### Template d'issue
+
+Lors de l'ouverture d'une issue, incluez :
+
+```markdown
+## Description du problème
+[Description claire]
+
+## Environnement
+- Node.js version: 
+- Provider version: 
+- AI SDK version: 
+- OS: 
+
+## Code pour reproduire
+\`\`\`typescript
+// Votre code
+\`\`\`
+
+## Erreur
+\`\`\`
+// Stack trace ou message d'erreur
+\`\`\`
+
+## Comportement attendu
+[Ce qui devrait se passer]
+
+## Comportement actuel
+[Ce qui se passe réellement]
+```
+
+## Prochaines étapes
+
+- [Best Practices](/docs/best-practices) - Éviter les problèmes courants
+- [Guide d'utilisation](/docs/guide) - Patterns recommandés
+- [API Reference](/docs/api) - Documentation complète