harness-toolkit-plugin-example

Minimal example plugin for harness-toolkit. Copy-paste this package as the starting point for your own plugin.

What this plugin does

Provides one command: harness-toolkit hello say — outputs "Hello from harness-toolkit-plugin-example!".

That's it. The plugin exists to demonstrate the full plugin authoring pattern in its simplest form.

Plugin authoring pattern

Required files

| File | Purpose | |------|---------| | package.json | "type": "commonjs", "main": "./dist/index.js", oclif.commands pointing to ./dist/commands, build: "tsc -p tsconfig.build.json && oclif manifest" | | tsconfig.build.json | Extends ../../tsconfig.base.json (or a root tsconfig). Sets outDir: ./dist, rootDir: ./src. | | src/index.ts | Exports a named register function — the entry point the harness-toolkit init hook calls. | | src/commands/**/*.ts | One file per command. Nested directories create nested topics (hello/say.ts → hello say). | | oclif.manifest.json | Auto-generated by oclif manifest. Must be included in published output ("files": ["dist", "oclif.manifest.json"]). |

How register() works

import type { PluginContract } from 'harness-toolkit'
import type { Config } from '@oclif/core'

export const register: PluginContract['register'] = function (_cli: Config): void {
  // Plugin-level setup goes here (optional).
  // Commands in src/commands/ are loaded automatically via the manifest.
}

The harness-toolkit init hook:

1. Scans node_modules for harness-toolkit-plugin-* packages.
2. Calls require(pluginRoot) to load the plugin.
3. Checks that pluginModule.register is a function — if missing, the plugin is skipped with a warning.
4. Loads commands from dist/commands/ via the oclif Plugin object.
5. Calls register(config) for any plugin-level setup.

Your register() body can be empty if you have no plugin-level setup. Commands load regardless.

Commands

Commands extend Command from @oclif/core:

import { Command } from '@oclif/core'

export class Say extends Command {
  static description = 'My command description'

  async run(): Promise<void> {
    this.log('Hello!')
  }
}

Building

pnpm install        # or npm install — wire workspace symlinks first
pnpm run build      # tsc -p tsconfig.build.json && oclif manifest

Both steps are required. oclif manifest generates oclif.manifest.json which the init hook uses to load your commands. Missing manifest = harness-toolkit startup is catastrophically slow on the first run.

Publishing

npm publish

Consumers install with:

npm install harness-toolkit-plugin-yourname

After install, restart harness-toolkit — your commands appear automatically in harness-toolkit --help.

Package name convention

Plugin packages must follow the naming convention harness-toolkit-plugin-<slug> for auto-discovery. The harness-toolkit init hook filters node_modules for this prefix.