Plugin Publish

What this skill does

# plugin.publish

## Overview

**plugin.publish** is the publication tool that distributes your bundled Betty Framework plugin packages to various targets. It validates package integrity via SHA256 checksums and handles publication to local directories, Claude Marketplace endpoints, or GitHub Releases with automatic creation support. Includes `--dry-run` and `--validate-only` modes for safe testing.

## Purpose

Automates secure plugin distribution by:
- **Validating** SHA256 checksums to ensure package integrity
- **Publishing** to local directories for testing and archival
- **Uploading** to Claude Marketplace API endpoint (simulated, ready for production)
- **Creating** GitHub Releases automatically using gh CLI
- **Tracking** publication metadata for auditing and governance
- **Testing** with dry-run mode before actual publication
- **Validating** packages without publishing using validate-only mode

This ensures consistent, traceable, and secure plugin distribution across all deployment targets.

## What It Does

1. **Validates Package**: Verifies the .tar.gz file exists and is readable
2. **Calculates Checksums**: Computes MD5 and SHA256 hashes for integrity verification
3. **Validates SHA256**: Compares against expected checksum from manifest.json
4. **Loads Metadata**: Extracts plugin info from manifest.json (name, version, author, etc.)
5. **Publishes to Target**:
   - **local**: Copies to `dist/published/` with metadata
   - **marketplace**: POSTs JSON metadata to Claude Marketplace API (simulated)
   - **gh-release**: Creates GitHub Release using gh CLI (with auto-create option)
6. **Supports Modes**:
   - **--dry-run**: Shows what would be done without making changes
   - **--validate-only**: Only validates checksums without publishing
   - **--auto-create**: Automatically creates GitHub Release using gh CLI
7. **Generates Metadata**: Creates publication records for auditing
8. **Reports Results**: Returns publication status with paths and checksums

## Usage

### Basic Usage (Local Target)

```bash
python skills/plugin.publish/plugin_publish.py dist/betty-framework-1.0.0.tar.gz
```

Publishes with defaults:
- Target: `local` (dist/published/)
- Checksum validation: Auto-detected from manifest.json

### Via Betty CLI

```bash
/plugin/publish dist/betty-framework-1.0.0.tar.gz
```

### Publish to Specific Target

```bash
# Publish to local directory
python skills/plugin.publish/plugin_publish.py \
  dist/betty-framework-1.0.0.tar.gz \
  --target=local

# Publish to Claude Marketplace (simulated)
python skills/plugin.publish/plugin_publish.py \
  dist/betty-framework-1.0.0.tar.gz \
  --target=marketplace

# Prepare GitHub Release (files only, manual creation needed)
python skills/plugin.publish/plugin_publish.py \
  dist/betty-framework-1.0.0.tar.gz \
  --target=gh-release

# Create GitHub Release automatically using gh CLI
python skills/plugin.publish/plugin_publish.py \
  dist/betty-framework-1.0.0.tar.gz \
  --target=gh-release \
  --auto-create
```

### Dry Run and Validation Modes

```bash
# Dry run - show what would happen without making changes
python skills/plugin.publish/plugin_publish.py \
  dist/betty-framework-1.0.0.tar.gz \
  --target=marketplace \
  --dry-run

# Validate only - check checksums without publishing
python skills/plugin.publish/plugin_publish.py \
  dist/betty-framework-1.0.0.tar.gz \
  --validate-only

# Dry run with GitHub Release
python skills/plugin.publish/plugin_publish.py \
  dist/betty-framework-1.0.0.tar.gz \
  --target=gh-release \
  --auto-create \
  --dry-run
```

### With Explicit Checksum Validation

```bash
python skills/plugin.publish/plugin_publish.py \
  dist/betty-framework-1.0.0.tar.gz \
  --target=local \
  --sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
```

### With Custom Manifest Path

```bash
python skills/plugin.publish/plugin_publish.py \
  /tmp/betty-framework-1.0.0.tar.gz \
  --target=release \
  --manifest=/tmp/manifest.json
```

### With Custom Marketplace Endpoint

```bash
python skills/plugin.publish/plugin_publish.py \
  dist/betty-framework-1.0.0.tar.gz \
  --target=marketplace \
  --endpoint=https://api.example.com/plugins/upload
```

## Command-Line Arguments

| Argument | Type | Default | Description |
|----------|------|---------|-------------|
| `package_path` | Positional | Required | Path to the .tar.gz package file |
| `--target` | Option | `local` | Publication target: `local`, `marketplace`, or `gh-release` |
| `--sha256` | Option | Auto-detect | Expected SHA256 checksum for validation |
| `--manifest` | Option | Auto-detect | Path to manifest.json |
| `--endpoint` | Option | Claude Marketplace | Marketplace API endpoint URL (for `marketplace` target) |
| `--dry-run` | Flag | False | Show what would be done without making changes |
| `--validate-only` | Flag | False | Only validate checksums without publishing |
| `--auto-create` | Flag | False | Automatically create GitHub Release using gh CLI (for `gh-release` target) |

## Publication Targets

### Local Target

**Purpose**: Copy package to local published directory for testing, archival, or internal distribution.

**Output Location**: `dist/published/`

**Generated Files**:
- `{package-name}.tar.gz` - Copied package file
- `{package-name}.tar.gz.publish.json` - Publication metadata

**Use Cases**:
- Local testing before remote publication
- Internal company archives
- Offline distribution
- Backup copies

**Example**:
```bash
python skills/plugin.publish/plugin_publish.py \
  dist/betty-framework-1.0.0.tar.gz \
  --target=local
```

**Output**:
```
dist/published/
├── betty-framework-1.0.0.tar.gz
└── betty-framework-1.0.0.tar.gz.publish.json
```

### Marketplace Target

**Purpose**: Upload plugin metadata to Claude Marketplace API endpoint (currently simulated).

**Output Location**: `dist/published/marketplace/`

**Generated Files**:
- `{package-name}.tar.gz.marketplace-publish.json` - Simulation log with request/response

**Use Cases**:
- Publish to Claude Code Marketplace
- Upload to custom plugin repository
- Submit to enterprise plugin registry

**Current Implementation**: SIMULATED
- Generates complete HTTP POST request with JSON metadata
- Returns mock successful response
- No actual network request made
- Ready for real implementation (add requests library)

**Example**:
```bash
# Standard marketplace publication (simulated)
python skills/plugin.publish/plugin_publish.py \
  dist/betty-framework-1.0.0.tar.gz \
  --target=marketplace

# With custom endpoint
python skills/plugin.publish/plugin_publish.py \
  dist/betty-framework-1.0.0.tar.gz \
  --target=marketplace \
  --endpoint=https://marketplace.claude.ai/api/v1/plugins

# Dry run first to see what would happen
python skills/plugin.publish/plugin_publish.py \
  dist/betty-framework-1.0.0.tar.gz \
  --target=marketplace \
  --dry-run
```

**JSON Metadata Structure**:
```json
{
  "plugin": {
    "name": "betty-framework",
    "version": "1.0.0",
    "description": "...",
    "author": { ... },
    "license": "MIT",
    "homepage": "...",
    "repository": "...",
    "tags": [...],
    "betty_version": ">=0.1.0"
  },
  "package": {
    "filename": "betty-framework-1.0.0.tar.gz",
    "size_bytes": 524288,
    "checksums": {
      "md5": "...",
      "sha256": "..."
    }
  },
  "submitted_at": "2025-10-24T12:00:00.000000+00:00"
}
```

### GitHub Release Target

**Purpose**: Create GitHub Releases with auto-generated release notes and automatic upload support.

**Output Location**: `dist/published/releases/`

**Generated Files**:
- `{package-name}.tar.gz` - Copied package file
- `RELEASE_NOTES_v{version}.md` - Auto-generated release notes
- `{package-name}.tar.gz.release.json` - Release metadata

**Use Cases**:
- GitHub Releases publication (manual or automatic)
- Public open-source distribution
- Versioned releases with auto-generated notes
- Official product releases

**Modes**:
1. **Preparation Only** (default): Prepares files fo