openpets 1.0.4 → 1.0.5

package/ai-client-base/index.ts

@@ -44,6 +44,27 @@ export abstract class BaseAIClient {
 
   abstract get providerName(): string
 
+  protected log(message: string, level: "info" | "warn" | "error" | "debug" = "info"): void {
+    if (!this.debug && level === "debug") return
+
+    const timestamp = new Date().toISOString()
+    const prefix = `[${this.providerName.toUpperCase()}] ${timestamp}`
+
+    switch (level) {
+      case "error":
+        console.error(`${prefix} ERROR:`, message)
+        break
+      case "warn":
+        console.warn(`${prefix} WARN:`, message)
+        break
+      case "debug":
+        console.debug(`${prefix} DEBUG:`, message)
+        break
+      default:
+        console.log(`${prefix} INFO:`, message)
+    }
+  }
+
   protected ensureApiKey(envVarName: string): void {
     if (!this.apiKey || this.apiKey.trim() === "") {
       throw new Error(`${envVarName} environment variable is required but not set`)
@@ -114,4 +135,95 @@ export abstract class BaseAIClient {
     }
     return mimeTypes[ext] || 'application/octet-stream'
   }
+
+  protected async downloadAndOpen<T extends AIImageResult | AIVideoResult>(
+    result: T,
+    mediaType: "image" | "video",
+    fileExtension: string,
+    openInViewer: boolean = true
+  ): Promise<T & { localPath?: string }> {
+    if (!result.success) {
+      return result
+    }
+
+    const mediaArray = mediaType === "image"
+      ? (result as AIImageResult).images
+      : (result as AIVideoResult).videos
+
+    if (!mediaArray || mediaArray.length === 0) {
+      return result
+    }
+
+    try {
+      const downloadsDir = path.join(process.cwd(), "output")
+      if (!fs.existsSync(downloadsDir)) {
+        fs.mkdirSync(downloadsDir, { recursive: true })
+      }
+
+      const timestamp = Date.now()
+      const filename = `${this.providerName}-${mediaType}-${timestamp}.${fileExtension}`
+      const localPath = path.join(downloadsDir, filename)
+
+      const response = await fetch(mediaArray[0].url)
+      if (!response.ok) {
+        throw new Error(`Failed to download: ${response.statusText}`)
+      }
+
+      const buffer = await response.arrayBuffer()
+      fs.writeFileSync(localPath, Buffer.from(buffer))
+
+      logger.info(`${mediaType} saved to ${localPath}`)
+
+      if (openInViewer) {
+        await this.openInDefaultViewer(localPath)
+      }
+
+      return {
+        ...result,
+        localPath
+      }
+    } catch (error: any) {
+      this.log(
+        `${mediaType.charAt(0).toUpperCase() + mediaType.slice(1)} generated successfully but post-processing failed: ${error.message}`,
+        "error"
+      )
+
+      return {
+        ...result,
+        localPath: undefined
+      }
+    }
+  }
+
+  protected extractCreditsFromResponse(response: any): any {
+    const credits: any = {}
+
+    if (response?.credits !== undefined) {
+      credits.balance = response.credits.balance
+      credits.cost = response.credits.cost
+      credits.currency = response.credits.currency
+      credits.remaining = response.credits.remaining
+      credits.limit = response.credits.limit
+      credits.used = response.credits.used
+    }
+
+    if (response?.billing !== undefined) {
+      credits.balance = response.billing.balance
+      credits.cost = response.billing.cost
+      credits.currency = response.billing.currency
+      credits.remaining = response.billing.remaining
+    }
+
+    if (response?.usage !== undefined) {
+      credits.used = response.usage.total_tokens || response.usage.used
+      credits.limit = response.usage.limit
+      credits.remaining = response.usage.remaining
+    }
+
+    if (Object.keys(credits).length === 0) {
+      return undefined
+    }
+
+    return credits
+  }
 }

package/cli.ts

@@ -7,6 +7,74 @@ import { spawn } from 'child_process'
 import { resolve } from 'path'
 import { readFileSync, existsSync } from 'fs'
 
+async function publishPet(petName: string | undefined, options: { preview?: boolean; channel?: string } = {}) {
+  const { preview = false, channel = 'latest' } = options
+
+  // Find the script path - try multiple locations
+  let scriptPath = resolve(__dirname, '../../scripts/publish-pet.ts')
+  if (!existsSync(scriptPath)) {
+    // We might be in a different location, try relative to cwd
+    scriptPath = resolve(process.cwd(), '../../scripts/publish-pet.ts')
+  }
+
+  if (!existsSync(scriptPath)) {
+    console.error(`❌ Publish script not found: ${scriptPath}`)
+    console.error(`   Tried: ${resolve(__dirname, '../../scripts/publish-pet.ts')}`)
+    console.error(`   And: ${resolve(process.cwd(), '../../scripts/publish-pet.ts')}`)
+    process.exit(1)
+  }
+
+  // If no petName provided, try to infer from current directory
+  let finalPetName = petName
+  if (!finalPetName) {
+    const cwd = process.cwd()
+    const pkgPath = resolve(cwd, 'package.json')
+
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+        // Extract pet name from @openpets/maps -> maps
+        if (pkg.name && pkg.name.startsWith('@openpets/')) {
+          finalPetName = pkg.name.replace('@openpets/', '')
+          console.log(`📦 Detected pet: ${finalPetName}`)
+        }
+      } catch (e) {
+        // Ignore parse errors
+      }
+    }
+
+    if (!finalPetName) {
+      console.error('❌ Could not determine pet name. Run from pet directory or specify pet name.')
+      process.exit(1)
+    }
+  }
+
+  const bunArgs = [scriptPath, finalPetName]
+  if (preview) bunArgs.push('--preview')
+  if (channel && channel !== 'latest') bunArgs.push('--channel', channel)
+
+  return new Promise<void>((resolve, reject) => {
+    const child = spawn('bun', bunArgs, {
+      stdio: 'inherit',
+      shell: true,
+      env: {
+        ...process.env,
+        OPENPETS_PREVIEW: preview ? 'true' : 'false',
+        OPENPETS_CHANNEL: channel
+      }
+    })
+
+    child.on('error', reject)
+    child.on('exit', (code) => {
+      if (code !== 0) {
+        reject(new Error(`Publish exited with code ${code}`))
+      } else {
+        resolve()
+      }
+    })
+  })
+}
+
 const args = process.argv.slice(2)
 const command = args[0]
 
@@ -156,6 +224,18 @@ if (command === 'build') {
     log('Deploy error details:', error)
     process.exit(1)
   })
+} else if (command === 'publish') {
+  const petName = args[1] && !args[1].startsWith('--') ? args[1] : undefined
+  const preview = args.includes('--preview')
+  const channelIndex = args.indexOf('--channel')
+  const channel = channelIndex >= 0 ? args[channelIndex + 1] : 'latest'
+
+  log('Publishing pet:', petName || '(auto-detect)', { preview, channel })
+  publishPet(petName, { preview, channel }).catch(error => {
+    console.error('Error publishing pet:', error)
+    log('Publish error details:', error)
+    process.exit(1)
+  })
 } else if (!command) {
   log('No command provided, launching manager UI')
   launchManager()
@@ -164,16 +244,25 @@ if (command === 'build') {
   console.error('Usage: pets [command] [options]')
   console.error('')
   console.error('Commands:')
-  console.error('  (none)             Launch the plugin manager UI (default)')
-  console.error('  build <pet-name>   Build and validate a pet package')
-  console.error('  deploy <pet-name>  Build and deploy a pet package with metadata')
+  console.error('  (none)                Launch the plugin manager UI (default)')
+  console.error('  build <pet-name>      Build and validate a pet package')
+  console.error('  deploy <pet-name>     Build and deploy a pet package with metadata')
+  console.error('  publish [pet-name]    Publish a pet package to npm (auto-detects if in pet dir)')
+  console.error('')
+  console.error('Publish Options:')
+  console.error('  --preview             Dry-run mode (no actual publish)')
+  console.error('  --channel <name>      Publish to a specific npm tag (default: latest)')
   console.error('')
   console.error('Examples:')
-  console.error('  pets               # Launch the desktop plugin manager')
+  console.error('  pets                  # Launch the desktop plugin manager')
   console.error('  pets build postgres')
   console.error('  pets deploy maps')
+  console.error('  pets publish maps                    # From root directory')
+  console.error('  cd pets/maps && pets publish         # From pet directory')
+  console.error('  pets publish --preview               # Dry-run from pet directory')
+  console.error('  pets publish maps --channel beta')
   console.error('')
   console.error('Environment:')
-  console.error('  PETS_DEBUG=true    Enable detailed debug logging')
+  console.error('  PETS_DEBUG=true       Enable detailed debug logging')
   process.exit(1)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openpets",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "type": "module",
   "description": "Core package for OpenPets - AI plugin infrastructure and shared utilities",
   "main": "index.ts",
@@ -15,7 +15,16 @@
     "*.d.ts",
     "ai-client-base/**/*",
     "!**/*.test.ts",
-    "!**/*.test.js"
+    "!**/*.test.js",
+    "!.env*",
+    "!*.pem",
+    "!*.key",
+    "!credentials*.json",
+    "!*.p12",
+    "!*.pfx",
+    "!reference",
+    "!reports",
+    "!report"
   ],
   "keywords": [
     "ai",
@@ -42,4 +51,4 @@
   "peerDependencies": {
     "@opencode-ai/plugin": "^1.0.106"
   }
-}
+}

package/plugin-factory.ts

@@ -285,16 +285,7 @@ export function loadEnv(petId?: string): EnvConfig {
       }
     }
 
-    for (const [key, value] of Object.entries(process.env)) {
-      if (value && value.length > 0) {
-        if (!envVars[key]) {
-          envVars[key] = value
-          logger.debug(`Loaded from process.env: ${key}`)
-        }
-      }
-    }
-
-    logger.info(`Loaded ${Object.keys(envVars).length} environment variables`)
+    logger.info(`Loaded ${Object.keys(envVars).length} environment variables from project config`)
 
   } catch (error: any) {
     logger.error(`Error loading environment variables: ${error.message}`)

package/validate-pet.ts

@@ -39,6 +39,10 @@ export class PluginValidator {
     'scenarios'
   ]
 
+  private recommendedFields = [
+    'providers'
+  ]
+
   private requiredScripts = [
     'test:all'
   ]
@@ -158,9 +162,27 @@ export class PluginValidator {
       warnings.push('No scripts defined - consider adding test scripts')
     }
 
+    // Validate providers structure if present
+    const validProviderIds = new Set<string>()
+    if (pkg.providers) {
+      const providersValidation = this.validateProviders(pkg.providers)
+      errors.push(...providersValidation.errors)
+      warnings.push(...providersValidation.warnings)
+
+      if (Array.isArray(pkg.providers)) {
+        pkg.providers.forEach((provider: any) => {
+          if (provider.id) {
+            validProviderIds.add(provider.id)
+          }
+        })
+      }
+    } else if (pkg.envVariables) {
+      warnings.push('Missing recommended field "providers" - consider defining providers with credentialsUrl for better documentation')
+    }
+
     // Validate envVariables structure if present
     if (pkg.envVariables) {
-      const envValidation = this.validateEnvVariables(pkg.envVariables)
+      const envValidation = this.validateEnvVariables(pkg.envVariables, validProviderIds)
       errors.push(...envValidation.errors)
       warnings.push(...envValidation.warnings)
     }
@@ -206,6 +228,9 @@ export class PluginValidator {
     // Check for .env.example
     if (pkg.envVariables && !existsSync(join(pluginPath, '.env.example'))) {
       errors.push('envVariables defined but .env.example file missing - create this file to document required environment variables')
+    } else if (pkg.envVariables && existsSync(join(pluginPath, '.env.example'))) {
+      const envExampleValidation = this.validateEnvExampleFile(join(pluginPath, '.env.example'), pkg.envVariables, pkg.providers)
+      warnings.push(...envExampleValidation.warnings)
     }
 
     // Check for README
@@ -223,7 +248,72 @@ export class PluginValidator {
     }
   }
 
-  private validateEnvVariables(envVars: any): ValidationResult {
+  private validateProviders(providers: any): ValidationResult {
+    const errors: string[] = []
+    const warnings: string[] = []
+
+    if (!Array.isArray(providers)) {
+      errors.push('providers must be an array')
+      return { valid: false, errors, warnings }
+    }
+
+    if (providers.length === 0) {
+      warnings.push('providers array is empty - add at least one provider definition')
+      return { valid: true, errors, warnings }
+    }
+
+    const seenIds = new Set<string>()
+
+    providers.forEach((provider: any, index: number) => {
+      if (typeof provider !== 'object' || provider === null) {
+        errors.push(`providers[${index}] must be an object`)
+        return
+      }
+
+      if (!provider.id) {
+        errors.push(`providers[${index}] missing required field "id"`)
+      } else if (typeof provider.id !== 'string') {
+        errors.push(`providers[${index}].id must be a string`)
+      } else {
+        if (seenIds.has(provider.id)) {
+          errors.push(`providers[${index}] duplicate provider id "${provider.id}"`)
+        }
+        seenIds.add(provider.id)
+      }
+
+      if (!provider.name) {
+        warnings.push(`providers[${index}] missing recommended field "name"`)
+      } else if (typeof provider.name !== 'string') {
+        errors.push(`providers[${index}].name must be a string`)
+      }
+
+      if (!provider.credentialsUrl) {
+        warnings.push(`providers[${index}] missing recommended field "credentialsUrl" for API key generation link`)
+      } else if (typeof provider.credentialsUrl !== 'string') {
+        errors.push(`providers[${index}].credentialsUrl must be a string`)
+      } else {
+        try {
+          new URL(provider.credentialsUrl.replace(/\{[^}]+\}/g, 'placeholder'))
+        } catch {
+          warnings.push(`providers[${index}].credentialsUrl should be a valid URL pattern`)
+        }
+      }
+
+      if (provider.credentialsDocUrl && typeof provider.credentialsDocUrl !== 'string') {
+        errors.push(`providers[${index}].credentialsDocUrl must be a string`)
+      } else if (provider.credentialsDocUrl) {
+        try {
+          new URL(provider.credentialsDocUrl)
+        } catch {
+          warnings.push(`providers[${index}].credentialsDocUrl should be a valid URL`)
+        }
+      }
+    })
+
+    return { valid: errors.length === 0, errors, warnings }
+  }
+
+  private validateEnvVariables(envVars: any, validProviderIds: Set<string>): ValidationResult {
     const errors: string[] = []
     const warnings: string[] = []
 
@@ -245,8 +335,14 @@ export class PluginValidator {
         if (!envVar.description) {
           warnings.push(`envVariables.${type}[${index}] missing description field`)
         }
-        if (!envVar.provider) {
-          warnings.push(`envVariables.${type}[${index}] missing provider field`)
+        if (!envVar.providerId) {
+          warnings.push(`envVariables.${type}[${index}] missing providerId field - should reference a provider in the providers array`)
+        } else if (typeof envVar.providerId === 'string') {
+          if (validProviderIds.size > 0 && !validProviderIds.has(envVar.providerId)) {
+            errors.push(`envVariables.${type}[${index}].providerId "${envVar.providerId}" does not match any provider id in the providers array`)
+          }
+        } else {
+          errors.push(`envVariables.${type}[${index}].providerId must be a string`)
         }
         if (typeof envVar.priority !== 'number') {
           warnings.push(`envVariables.${type}[${index}] missing or invalid priority field`)
@@ -264,6 +360,65 @@ export class PluginValidator {
     return { valid: errors.length === 0, errors, warnings }
   }
 
+  private validateEnvExampleFile(envExamplePath: string, envVars: any, providers: any[]): { warnings: string[] } {
+    const warnings: string[] = []
+
+    try {
+      const envExampleContent = readFileSync(envExamplePath, 'utf-8')
+      const envExampleLines = envExampleContent.split('\n')
+
+      const documentedVars = new Set<string>()
+      const providerComments = new Map<string, boolean>()
+
+      for (let i = 0; i < envExampleLines.length; i++) {
+        const line = envExampleLines[i].trim()
+
+        if (line.startsWith('#') && (line.includes('http://') || line.includes('https://'))) {
+          const nextLine = envExampleLines[i + 1]?.trim()
+          if (nextLine && nextLine.includes('=')) {
+            const varName = nextLine.split('=')[0].trim()
+            providerComments.set(varName, true)
+          }
+        }
+
+        if (line && !line.startsWith('#') && line.includes('=')) {
+          const varName = line.split('=')[0].trim()
+          documentedVars.add(varName)
+        }
+      }
+
+      const allEnvVars: any[] = [
+        ...(envVars.required || []),
+        ...(envVars.optional || [])
+      ]
+
+      const providerMap = new Map<string, any>()
+      if (providers && Array.isArray(providers)) {
+        providers.forEach(provider => {
+          if (provider.id) {
+            providerMap.set(provider.id, provider)
+          }
+        })
+      }
+
+      for (const envVar of allEnvVars) {
+        if (!documentedVars.has(envVar.name)) {
+          warnings.push(`Environment variable "${envVar.name}" defined in package.json but not found in .env.example`)
+        } else if (!providerComments.has(envVar.name) && envVar.providerId) {
+          const provider = providerMap.get(envVar.providerId)
+          if (provider && provider.credentialsUrl) {
+            warnings.push(`Environment variable "${envVar.name}" in .env.example missing comment with provider credentialsUrl (${provider.credentialsUrl})`)
+          }
+        }
+      }
+
+    } catch (error) {
+      warnings.push(`Could not validate .env.example file: ${error instanceof Error ? error.message : String(error)}`)
+    }
+
+    return { warnings }
+  }
+
   private validateScenarios(scenarios: any): ValidationResult {
     const errors: string[] = []
     const warnings: string[] = []