Publishing Plugins

This page covers how to prepare, build, and publish a V2 plugin to the Hone marketplace.

Manifest Requirements

Every published plugin needs a complete plugin.json:

{
  "id": "com.example.my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "A short description of what the plugin does",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "license": "MIT",
  "engines": {
    "hone": ">=1.0.0"
  },
  "main": "src/index.ts",
  "capabilities": {
    "editor": {
      "read": true,
      "write": true
    },
    "ui": {
      "commandPalette": true,
      "notifications": true
    }
  },
  "contributes": {
    "commands": [
      {
        "id": "my-plugin.run",
        "title": "Run My Plugin"
      }
    ]
  }
}

Required Fields

Field	Description
`id`	Globally unique identifier (reverse-domain convention)
`name`	Display name shown in the marketplace
`version`	Semver version string
`description`	Short description (shown in search results)
`author`	Author name and contact
`license`	SPDX license identifier
`engines.hone`	Minimum compatible Hone version
`main`	Entry point TypeScript file
`capabilities`	Declared capabilities (determines execution tier)

Validating the Manifest

Use validateManifest from @hone/sdk to check your manifest before submission:

import { validateManifest } from '@hone/sdk';

const errors = validateManifest('./plugin.json');
if (errors.length > 0) {
  console.error('Manifest errors:', errors);
}

When you submit a plugin, the build service (hone-build, port 8447) sends it to perry-hub workers for compilation. You submit TypeScript source code; the service produces native binaries for all supported platforms:

Platform	Architectures
macOS	x86_64, aarch64
Windows	x86_64
Linux	x86_64, aarch64
iOS	aarch64 (if applicable)
Android	aarch64 (if applicable)

You do not need to compile for each platform yourself. The build service handles cross-compilation.

Publishing Flow

Develop and test locally. Compile with perry compile src/index.ts --output my-plugin and test against a local Hone instance.
Validate the manifest. Run validateManifest to catch issues before submission.
Submit to the marketplace. Use the CLI or the marketplace client from @hone/sdk:
```
hone plugin publish
```
This uploads your source to the build service, which compiles for all platforms and registers the result with the marketplace server (hone-marketplace, port 8446).
Build service compiles. perry-hub workers produce native shared libraries for each platform/architecture combination.
Plugin goes live. Once all platform builds succeed, the plugin appears in the Hone marketplace. Users can discover and install it from within the IDE.

Versioning

Follow semver:

Patch (1.0.0 -> 1.0.1): Bug fixes, no API changes
Minor (1.0.0 -> 1.1.0): New features, backward compatible
Major (1.0.0 -> 2.0.0): Breaking changes

Each published version creates a new marketplace entry. Previous versions remain available. Users can:

Auto-update within a major version (default)
Pin to a specific version
Roll back to any previously published version

Pre-publication Checklist

plugin.json passes validateManifest with no errors
Plugin compiles locally with perry compile
All declared capabilities are actually used
No unnecessary capabilities declared (principle of least privilege)
Version number incremented from previous release
Description and metadata are accurate
License is specified and correct

Hone Documentation