TypeScript SDK for building nullplatform plugins. Handles gRPC transport (HashiCorp go-plugin protocol), action routing, --describe, and --publish.

Install

bun add @nullplatform/plugin

Usage

Scope plugin

import { defineScope } from "@nullplatform/plugin/scope";

defineScope({
  name: "kubernetes-k3d",
  version: "0.0.1",
  category: "containers",
  provider: "kubernetes",

  schema: {
    type: "object",
    properties: {
      memory: { type: "string", default: "2Gi" },
    },
  },

  actions: {
    "create-scope": {
      input: { type: "object" },
      handler: async (notification, emit) => {
        // provision infrastructure
        return { domain: "app.k3d.local" };
      },
    },
  },
});

Simple plugin (custom command)

import { createPlugin, registerManifest } from "@nullplatform/plugin";

registerManifest({ name: "my-plugin", version: "0.0.1", command_types: ["custom"] });

createPlugin({
  async execute(req) {
    return { success: true, data: { message: "done" } };
  },
}).start();

Subpath exports

| Import | Description | |---|---| | @nullplatform/plugin | Core: createPlugin, registerManifest, types | | @nullplatform/plugin/scope | defineScope API | | @nullplatform/plugin/schema | JSON Schema type inference | | @nullplatform/plugin/testing | Test harness: startPluginProcess, factories | | @nullplatform/plugin/workflow | Workflow integration (StreamingExecutionObserver) |

CLI integration

Plugins are scaffolded with np plugin init and managed via mise tasks:

mise run dev          # local dev with hot reload
mise run dev:agent    # dev with np-agent attached
mise run test         # run tests
mise run build        # compile to standalone binary
mise run publish      # publish to platform