@kb-labs/plugin-template-cli

Reference CLI/REST/Studio plugin package for KB Labs Plugin Template.

Vision & Purpose

@kb-labs/plugin-template-cli is the canonical example plugin package used by @kb-labs/plugin-template.
It shows how to implement a plugin that exposes:

• a CLI command (Hello),
• a REST handler, and
• a Studio widget,

all driven by a single manifest and contracts package.

Package Status

• Version: 0.1.0
• Stage: Stable (template)
• Status: Reference Implementation ✅

Architecture

High-Level Overview

plugin-cli
    │
    ├──► contracts     (from @kb-labs/plugin-template-contracts)
    ├──► shared        (constants/helpers)
    ├──► domain        (Greeting entity and invariants)
    ├──► application   (use-cases: create greeting, etc.)
    ├──► cli           (Hello command wiring)
    ├──► rest          (Hello REST handler + schema)
    └──► studio        (Hello Studio widget)

Key Components

• src/domain/: Greeting entity and domain rules
• src/application/: use-cases that orchestrate domain logic
• src/cli/commands/hello/*: CLI command implementation
• src/rest/handlers/hello-handler.ts: REST handler bound to manifest
• src/studio/widgets/hello-widget.tsx: Studio widget implementation
• src/manifest.v2.ts: Plugin manifest v2 (CLI/REST/Studio wiring)

Features

• Single-source manifest for CLI/REST/Studio surfaces
• Layered architecture (shared → domain → application → interface)
• Type-safe contracts via @kb-labs/plugin-template-contracts
• Hello-world flow demonstrating end-to-end plugin wiring

Exports

From src/index.ts:

• manifest: Plugin Manifest V2
• All public surfaces:
  • CLI command exports
  • domain/application/shared re-exports

Dependencies

Runtime

• @kb-labs/setup-operations: reusable setup operations
• @kb-labs/plugin-manifest: manifest types and helpers
• @kb-labs/plugin-template-contracts: public contracts for this template plugin
• @kb-labs/shared-cli-ui: shared CLI UI helpers
• react, react-dom, zod

Development

• @kb-labs/devkit: shared TS/ESLint/Vitest/TSUP presets
• typescript, tsup, vitest, rimraf

Scripts

From kb-labs-plugin-template repo root:

pnpm install
pnpm --filter @kb-labs/plugin-template-cli build
pnpm --filter @kb-labs/plugin-template-cli test

To run sandboxes, see the root README.md (pnpm sandbox:cli, sandbox:rest, sandbox:studio).

Command Implementation

This template demonstrates three different approaches to implementing CLI commands:

1. High-level wrapper (defineCommand) - Recommended for most cases
2. Low-level atomic tools - For maximum control
3. Hybrid approach - Combining both

See COMMAND_IMPLEMENTATION_GUIDE.md for detailed explanations and examples.

Quick Start

The template:hello command in src/cli/commands/hello/run.ts shows all three approaches with working code examples. The default implementation uses Approach 1 (defineCommand), which provides:

• ✅ Zero-boilerplate flag validation
• ✅ Automatic analytics integration
• ✅ Structured logging
• ✅ Error handling
• ✅ Timing tracking
• ✅ JSON output mode

Customising for Your Plugin

When using this as a starting point:

• Rename the package in package.json (e.g. @kb-labs/my-plugin-cli)
• Update manifest IDs and the contracts package
• Replace the Hello flow with your own domain, use-cases, and surfaces
• Choose the command implementation approach that fits your needs (see COMMAND_IMPLEMENTATION_GUIDE.md)