Pets

Appearance

Config Schema ​

OpenPets validates .pets/config.json against a typed schema at runtime.

What gets validated ​

  • Top-level structure (enabled, disabled, envConfig, petConfig)
  • Value types for env vars and pet settings
  • schemaVersion compatibility

Schema fields ​

json
{
  "$schema": "https://pets.raggle.co/config.json",
  "schemaVersion": 1,
  "enabled": ["github"],
  "disabled": [],
  "envConfig": {
    "_global": {
      "OPENAI_API_KEY": "..."
    },
    "github": {
      "GITHUB_TOKEN": "..."
    }
  },
  "petConfig": {
    "_global": {
      "readOnly": false
    },
    "github": {
      "readOnly": true,
      "metricsEnabled": true
    },
    "typeform": {
      "formId": "abc123"
    }
  },
  "clients": {
    "my-api": {
      "output": "client/my-api.ts",
      "source": {
        "type": "openapi",
        "file": "../backend/client/openapi.json",
        "baseUrl": "https://api.example.com",
        "authType": "apiKey",
        "authEnvVar": "API_KEY",
        "apiKeyIn": "header",
        "apiKeyName": "X-API-Key"
      }
    }
  }
}

Prompt-safe project defaults ​

Pets can declare non-secret prompt defaults in their package.json with promptConfig.defaults. When a matching value is present in pets.json under petConfig.<pet>, pets intro includes it in the repo-specific instructions.

Example project config:

json
{
  "enabled": ["typeform"],
  "petConfig": {
    "typeform": {
      "formId": "abc123"
    }
  }
}

Only keys declared by the pet are rendered into prompts. Keep credentials in .env.pets or envConfig, not in prompt defaults.

Use pets config to discover and set prompt-safe values:

bash
pets config typeform
pets config typeform set formId abc123

Generated clients ​

pets client <client-id> can read a reusable client definition from pets.json under clients.<client-id>. This is useful when a repo wants to regenerate the same local TypeScript client from a pet or OpenAPI spec without repeating paths and auth settings.

Example:

json
{
  "clients": {
    "adapt-action-explorer-api": {
      "output": "client/adapt-action-explorer-api.ts",
      "source": {
        "type": "openapi",
        "file": "/path/to/backend/client/openapi.json",
        "baseUrl": "https://cdp-server-prod-pbybuiwoxq-uc.a.run.app",
        "authType": "apiKey",
        "authEnvVar": "API_KEY",
        "apiKeyIn": "header",
        "apiKeyName": "X-API-Key",
        "autoTestConnection": false,
        "responseFormat": "json"
      }
    }
  }
}

Then regenerate with:

bash
pets client adapt-action-explorer-api

Migration behavior ​

  • Missing schemaVersion is auto-set to 1
  • Legacy plugin arrays are migrated to enabled
  • Unsupported future schema versions return a clear error with fix guidance

SDK exports ​

  • PetsConfigSchema for programmatic validation
  • loadPetsConfigFile(path) for parse + validation
  • parsePetsConfig(raw) for in-memory validation
  • getConfig<T>(config, petId, key, fallback?) for typed pet/global lookup