@hcmguru/plugin-sdk

HCM.guru Plugin SDK — types, Zod schemas, pure helpers, and CLI for first-party and partner plugin authors.

Licensed under Apache-2.0. The SDK is intentionally licensed more permissively than the HCM.guru product (FSL-1.1-ALv2) so plugin authors can build, distribute, and sell plugins without friction.

Stability: this package is 0.x. Per semver, breaking changes may land in minor releases until 1.0.0. The public API is stabilising as first-party plugins migrate onto it.

Install

npm install --save-dev @hcmguru/plugin-sdk
# or, to use the scaffolding CLI globally
npm install -g @hcmguru/plugin-sdk

Quick start

# Scaffold a new plugin
npx hcm-plugin init my-plugin

Usage

import { definePlugin, defineAiTool } from "@hcmguru/plugin-sdk/define";
import type { AgentRunner, McpToolHandler } from "@hcmguru/plugin-sdk/runtime";
import { PluginManifestV05Schema } from "@hcmguru/plugin-sdk/manifest";

Entry points

| Import path | Contents | |---|---| | @hcmguru/plugin-sdk | All public exports (barrel) | | @hcmguru/plugin-sdk/manifest | Manifest Zod schemas + types | | @hcmguru/plugin-sdk/runtime | Runtime type-only contracts | | @hcmguru/plugin-sdk/define | Pure helper builders |

CLI

After building (npm run build), the hcm-plugin binary is available:

hcm-plugin init <name>            # Scaffold a new plugin
hcm-plugin build                  # Build with tsc
hcm-plugin pack [--sign <key>]    # Build + sign + zip
hcm-plugin sign keygen            # Generate ed25519 keypair
hcm-plugin dev                    # Watch mode (stub — not yet implemented)

Design

Types-first, no host runtime. The SDK exports type definitions, Zod schemas, and pure helpers. The actual runtime (route loader, agent dispatcher, MCP session manager, contract resolver, own-DB executor) stays in the host — plugins receive these via dependency injection at activation time.