Plugin Build

What this skill does

# plugin.build

## Overview

**plugin.build** is the packaging tool that bundles your Betty Framework plugin into a distributable archive ready for deployment to Claude Code. It validates all entrypoints, gathers necessary files, and creates versioned packages with checksums.

## Purpose

Automates the creation of deployable plugin packages by:
- **Validating** all declared entrypoints and handler files
- **Gathering** all necessary plugin files (skills, utilities, registries)
- **Packaging** into `.tar.gz` or `.zip` archives
- **Generating** checksums for package verification
- **Reporting** validation results and build metrics

This eliminates manual packaging errors and ensures consistent, reproducible plugin distributions.

## What It Does

1. **Loads plugin.yaml**: Reads the plugin configuration
2. **Validates Entrypoints**: Checks that all command handlers exist on disk
3. **Gathers Files**: Collects skills, utilities, registries, and documentation
4. **Creates Package**: Bundles everything into a versioned archive
5. **Calculates Checksums**: Generates MD5 and SHA256 hashes
6. **Generates Manifest**: Creates manifest.json with entrypoint summary and checksums
7. **Creates Preview**: Generates plugin.preview.yaml for review before deployment
8. **Generates Report**: Outputs detailed build metrics as JSON
9. **Reports Issues**: Identifies missing files or validation errors

## Usage

### Basic Usage

```bash
python skills/plugin.build/plugin_build.py
```

Builds with defaults:
- Plugin: `./plugin.yaml`
- Format: `tar.gz`
- Output: `./dist/`

### Via Betty CLI

```bash
/plugin/build
```

### Custom Plugin Path

```bash
python skills/plugin.build/plugin_build.py /path/to/plugin.yaml
```

### Specify Output Format

```bash
python skills/plugin.build/plugin_build.py --format=zip
```

```bash
python skills/plugin.build/plugin_build.py --format=tar.gz
```

### Custom Output Directory

```bash
python skills/plugin.build/plugin_build.py --output-dir=/tmp/packages
```

### Full Options

```bash
python skills/plugin.build/plugin_build.py \
  /custom/path/plugin.yaml \
  --format=zip \
  --output-dir=/var/packages
```

## Command-Line Arguments

| Argument | Type | Default | Description |
|----------|------|---------|-------------|
| `plugin_path` | Positional | `./plugin.yaml` | Path to plugin.yaml file |
| `--format` | Option | `tar.gz` | Package format (tar.gz or zip) |
| `--output-dir` | Option | `./dist` | Output directory for packages |

## Output Files

### Package Archive

**Naming convention**: `{plugin-name}-{version}.{format}`

Examples:
- `betty-framework-1.0.0.tar.gz`
- `betty-framework-1.0.0.zip`

**Location**: `{output-dir}/{package-name}.{format}`

### Manifest File

**Naming convention**: `manifest.json`

**Location**: `{output-dir}/manifest.json`

Contains plugin metadata, entrypoint summary, and package checksums. This is the primary file for plugin distribution and installation.

### Plugin Preview

**Naming convention**: `plugin.preview.yaml`

**Location**: `{output-dir}/plugin.preview.yaml`

Contains the current plugin configuration for review before deployment. Useful for comparing changes or validating the plugin structure.

### Build Report

**Naming convention**: `{plugin-name}-{version}-build-report.json`

Example:
- `betty-framework-1.0.0-build-report.json`

**Location**: `{output-dir}/{package-name}-build-report.json`

## Package Structure

The generated archive contains:

```
betty-framework-1.0.0/
├── plugin.yaml               # Plugin manifest
├── requirements.txt          # Python dependencies
├── README.md                 # Documentation (if exists)
├── LICENSE                   # License file (if exists)
├── CHANGELOG.md              # Change log (if exists)
├── betty/                    # Core utility package
│   ├── __init__.py
│   ├── config.py
│   ├── validation.py
│   ├── logging_utils.py
│   ├── file_utils.py
│   └── errors.py
├── registry/                 # Registry files
│   ├── skills.json
│   ├── commands.json
│   ├── hooks.json
│   └── agents.json
└── skills/                   # All active skills
    ├── api.define/
    │   ├── skill.yaml
    │   ├── SKILL.md
    │   └── api_define.py
    ├── api.validate/
    │   ├── skill.yaml
    │   ├── SKILL.md
    │   └── api_validate.py
    └── ... (all other skills)
```

## Manifest Schema

The `manifest.json` file is the primary metadata file for plugin distribution:

```json
{
  "name": "betty-framework",
  "version": "1.0.0",
  "description": "Betty Framework - Structured AI-assisted engineering",
  "author": {
    "name": "RiskExec",
    "email": "[email protected]",
    "url": "https://github.com/epieczko/betty"
  },
  "license": "MIT",
  "metadata": {
    "homepage": "https://github.com/epieczko/betty",
    "repository": "https://github.com/epieczko/betty",
    "documentation": "https://github.com/epieczko/betty/tree/main/docs",
    "tags": ["framework", "api-development", "workflow"],
    "generated_at": "2025-10-23T12:34:56.789012+00:00"
  },
  "requirements": {
    "python": ">=3.11",
    "packages": ["pyyaml"]
  },
  "permissions": ["filesystem:read", "filesystem:write", "process:execute"],
  "package": {
    "filename": "betty-framework-1.0.0.tar.gz",
    "size_bytes": 245760,
    "checksums": {
      "md5": "a1b2c3d4e5f6...",
      "sha256": "1234567890abcdef..."
    }
  },
  "entrypoints": [
    {
      "command": "skill/define",
      "handler": "skills/skill.define/skill_define.py",
      "runtime": "python"
    }
  ],
  "commands_count": 18,
  "agents": [
    {
      "name": "api.designer",
      "description": "Design APIs with iterative refinement"
    }
  ]
}
```

## Build Report Schema

```json
{
  "build_timestamp": "2025-10-23T12:34:56.789012+00:00",
  "plugin": {
    "name": "betty-framework",
    "version": "1.0.0",
    "description": "Betty Framework - Structured AI-assisted engineering"
  },
  "validation": {
    "total_commands": 18,
    "valid_entrypoints": 18,
    "missing_files": [],
    "has_errors": false
  },
  "package": {
    "path": "/home/user/betty/dist/betty-framework-1.0.0.tar.gz",
    "size_bytes": 245760,
    "size_human": "240.00 KB",
    "files_count": 127,
    "format": "tar.gz",
    "checksums": {
      "md5": "a1b2c3d4e5f6...",
      "sha256": "1234567890abcdef..."
    }
  },
  "entrypoints": [
    {
      "command": "skill/define",
      "handler": "skills/skill.define/skill_define.py",
      "runtime": "python",
      "path": "/home/user/betty/skills/skill.define/skill_define.py"
    }
  ]
}
```

## Outputs

### Success Response

```json
{
  "ok": true,
  "status": "success",
  "package_path": "/home/user/betty/dist/betty-framework-1.0.0.tar.gz",
  "report_path": "/home/user/betty/dist/betty-framework-1.0.0-build-report.json",
  "build_report": { ... }
}
```

### Success with Warnings

```json
{
  "ok": false,
  "status": "success_with_warnings",
  "package_path": "/home/user/betty/dist/betty-framework-1.0.0.tar.gz",
  "report_path": "/home/user/betty/dist/betty-framework-1.0.0-build-report.json",
  "build_report": {
    "validation": {
      "missing_files": [
        "Command 'api.broken': handler not found at skills/api.broken/api_broken.py"
      ],
      "has_errors": true
    }
  }
}
```

### Failure Response

```json
{
  "ok": false,
  "status": "failed",
  "error": "plugin.yaml not found: /home/user/betty/plugin.yaml"
}
```

## Behavior

### 1. Plugin Loading

Reads and parses `plugin.yaml`:
- Validates YAML syntax
- Extracts plugin name, version, description
- Identifies all command entrypoints

### 2. Entrypoint Validation

For each command in `plugin.yaml`:
- Extracts handler script path
- Checks file existence on disk
- Reports valid and missing handlers
- Logs validation results

**Valid entrypoint**:
```yaml
- name: skill/validate
  handler:
    runtime: python
    script: skills/skill.define/skill_define.py
```

**Missing handler** (reports warning):
```yaml
- name: broken/command
  handler:
    runt