npm package: @openpets/coder
Description: A unified version control plugin that supports both GitHub and GitLab. Automatically detects which platform to use based on git remote URL or environment variables and provides consistent APIs for issues, pull requests, branches, commits, CI/CD pipelines,
Latest version: 1.5.1

# Pet Plugin Template

A minimal template for creating OpenCode plugins. Copy this folder and customize it to build your own plugin.

## Quick Start

### 1. Copy This Template

```bash
# From pets directory
cp -r _TEMPLATE_ my-plugin
cd my-plugin
```

### 2. Customize

Edit these files:

**package.json:**
- Change `name` to `openpets/my-plugin`
- Update `description`
- Add your environment variables in `envVariables`
- Add example queries in `queries`

**index.ts:**
- Rename `TemplatePlugin` to `MyPlugin`
- Add your tools to the `tools` array
- Implement your logic in the `execute` functions

**opencode.json:**
- Update if needed (usually no changes required)

### 3. Test

```bash
npm install
npm run quickstart
```

## Basic Structure

```typescript
export const MyPlugin = async () => {
  const tools: ToolDefinition[] = [
    {
      name: "my-tool",
      description: "What this tool does",
      schema: z.object({
        param: z.string().describe("Parameter description")
      }),
      execute: async (args) => {
        // Your logic here
        return JSON.stringify({
          success: true,
          data: "result"
        })
      }
    }
  ]

  return createPlugin(tools)
}
```

## Adding Multiple Tools

Just add more tool definitions to the array:

```typescript
const tools: ToolDefinition[] = [
  {
    name: "tool-one",
    description: "First tool",
    schema: z.object({ /* ... */ }),
    execute: async (args) => { /* ... */ }
  },
  {
    name: "tool-two",
    description: "Second tool",
    schema: z.object({ /* ... */ }),
    execute: async (args) => { /* ... */ }
  }
]
```

## Using Utilities

Import utilities from `@/utils/`:

```typescript
// Example: Using Google Maps
const { GoogleMapsAPI } = await import("@/utils/google-maps")
const maps = new GoogleMapsAPI({ apiKey: process.env.GOOGLE_MAPS_API_KEY })
const result = await maps.geocode("New York")

// Example: Using FAL AI
const { createFalClient } = await import("@/utils/fal")
const fal = createFalClient()
```

## Environment Variables

Add to `package.json`:

```json
{
  "envVariables": {
    "required": [
      {
        "name": "MY_API_KEY",
        "description": "API key for my service",
        "provider": "My Service",
        "priority": 1
      }
    ],
    "optional": [
      {
        "name": "MY_CONFIG",
        "description": "Optional configuration",
        "provider": "Configuration",
        "priority": 2
      }
    ]
  }
}
```

Access in code:

```typescript
const apiKey = process.env.MY_API_KEY
```

## Schema Validation with Zod

Define your parameters with type safety:

```typescript
schema: z.object({
  // String
  name: z.string().describe("User name"),

  // Optional string with default
  greeting: z.string().optional().default("Hello").describe("Greeting"),

  // Number
  age: z.number().describe("User age"),

  // Enum
  type: z.enum(["user", "admin"]).describe("User type"),

  // Boolean
  active: z.boolean().describe("Is active"),

  // Array
  tags: z.array(z.string()).describe("Tags list")
})
```

## Return Format

Always return JSON string:

```typescript
// Success
return JSON.stringify({
  success: true,
  data: yourData,
  message: "Operation completed"
})

// Error
return JSON.stringify({
  success: false,
  error: "Error message"
})
```

## That's It!

You now have everything you need to build your own plugin. Keep it simple and add complexity as needed.

For more examples, check out other plugins in the `pets/` directory.