KB Labs Plugin Template

Gold standard reference template for building production-ready KB Labs plugins with CLI, REST, and Studio surfaces.

What makes this template special:

• ✅ 7,700+ lines of comprehensive documentation
• ✅ 100% canonical patterns (no legacy code)
• ✅ Production-ready examples (validation, testing, contracts, multi-tenancy)
• ✅ Complete error handling with 8 custom error classes
• ✅ KB Labs standard structure (cli, rest, studio, lifecycle, core, utils)

🚀 Quick start

# Clone and install
git clone https://github.com/kb-labs/kb-labs-plugin-template.git
cd kb-labs-plugin-template
pnpm install

# Build the plugin
pnpm --filter @kb-labs/plugin-template-core run build

# Run hello command
kb template:hello --name Developer
# Output: Hello, Developer!

🛠️ Using Shared Command Kit Helpers

This template demonstrates 86% boilerplate reduction using helpers from @kb-labs/shared-command-kit. Instead of writing 400+ lines of repetitive code, use declarative helpers.

Error Handling (defineError)

Before (400 lines of 8 custom error classes):

export class ValidationError extends Error {
  constructor(message: string, public field?: string, public details?: unknown) {
    super(message);
    this.name = 'ValidationError';
  }
}
// ... 7 more classes × 50 lines each = 400 lines

After (50 lines with defineError):

import { defineError, commonErrors } from '@kb-labs/shared-command-kit';

// Template-specific errors
export const TemplateError = defineError('TEMPLATE', {
  BusinessRuleViolation: {
    code: 400,
    message: (rule: string) => `Business rule violated: ${rule}`,
  },
  QuotaExceeded: {
    code: 429,
    message: (resource: string) => `Quota exceeded for ${resource}`,
  },
});

// Common errors (validation, not found, etc.)
export const CommonError = defineError('COMMON', commonErrors);

// Usage:
throw new TemplateError.BusinessRuleViolation('Insufficient funds');
throw new CommonError.ValidationFailed('Email must be valid');

Savings: 400 lines → 50 lines (87% reduction)

Permission Presets (permissions.combine)

Before (25 lines of manual permission blocks):

permissions: {
  fs: {
    mode: 'readWrite',
    allow: ['.kb/template/**', 'package.json'],
    deny: ['**/*.key', '**/*.secret', '**/node_modules/**'],
  },
  net: { allowHosts: ['localhost:*'] },
  env: { allow: ['NODE_ENV', 'KB_LABS_*', 'TEMPLATE_*'] },
  quotas: { timeoutMs: 60000, memoryMb: 512 },
}

After (10 lines with presets):

import { permissions } from '@kb-labs/shared-command-kit';

permissions: permissions.combine(
  permissions.presets.pluginWorkspace('template'),
  permissions.presets.localhost(),
  {
    env: { allow: ['TEMPLATE_*'] }, // Template-specific env vars
  }
)

Savings: 25 lines → 10 lines (60% reduction)

Schema Builders (schema.*)

Before (manual Zod schemas):

import { z } from 'zod';

export const HelloRequestSchema = z.object({
  name: z.string().min(1).max(100).optional(),
  cwd: z.string().optional(),
});

After (schema builders for clarity):

import { z } from 'zod';
import { schema } from '@kb-labs/shared-command-kit';

export const HelloRequestSchema = z.object({
  name: schema.text({ min: 1, max: 100 }).optional(),
  cwd: schema.cwd(),
});

Benefits: Clearer intent, reusable validation patterns

Analytics Tracking (withAnalytics)

Before (manual event tracking):

async handler(ctx, argv, flags) {
  ctx.logger?.info('Command started', { name: flags.name });

  const greeting = createGreeting(flags.name);

  ctx.logger?.info('Command completed', { message: greeting.message });
  return { ok: true, result: greeting };
}

After (automatic started/completed/failed events):

import { withAnalytics } from '@kb-labs/shared-command-kit';

async handler(ctx, argv, flags) {
  return await withAnalytics(
    ctx,
    'template.hello',
    {
      started: { name: flags.name },
      completed: (result) => ({ message: result.result?.message }),
      failed: (error) => ({ error: error.message }),
    },
    async () => {
      const greeting = createGreeting(flags.name);
      return { ok: true, result: greeting };
    }
  );
}

Benefits: Automatic event emission with duration tracking, consistent analytics

Available Helpers

| Helper | Purpose | Savings | |--------|---------|---------| | defineError() | Error factory | 87% (400→50 lines) | | permissions.combine() | Permission presets | 60% (25→10 lines) | | schema.* | Validation builders | Clarity + reuse | | defineSetupHandler() | Declarative lifecycle | 84% (126→20 lines) | | withAnalytics() | Auto analytics | +10 lines (feature) |

See also:

• Migration Guide - Migrate existing plugins
• shared-command-kit README - Full API reference
• utils/errors.ts - defineError example

📖 Documentation (7,700+ lines!)

Getting started

• 📘 Getting Started - Setup, build, and first steps
• 🏗️ Architecture - KB Labs folder structure and patterns
• 📦 Naming Convention - The Pyramid Rule (mandatory!)
• 🔄 Refactoring Guide - Migration from old DDD structure

Surface guides

• 🖥️ CLI Guide - Adding CLI commands with defineCommand
• 🌐 REST Guide - Adding REST handlers with Zod validation
• 🎨 Studio Guide - Creating React widgets for KB Labs UI

Comprehensive examples (2,500+ lines)

• ✅ Validation Examples - Zod schemas, custom validation, type inference
• 🧪 Test Examples - CLI, REST, widget, and integration testing
• 🔐 Contracts Examples - Type-safe IDs and hierarchical contracts
• 🏢 Multi-Tenancy Examples - SaaS patterns, rate limiting, quotas

Folder-specific READMEs (2,000+ lines)

• cli/README.md - CLI patterns and best practices (324 lines)
• rest/README.md - REST handlers with Zod (358 lines)
• studio/README.md - React widgets and layouts (443 lines)
• lifecycle/README.md - Setup, destroy, upgrade hooks (333 lines)
• core/README.md - Pure business logic (240 lines)
• utils/README.md - Utilities and error handling (348 lines)

🎯 What you get

KB Labs standard structure

packages/plugin-template-core/src/
├── cli/              # CLI commands (defineCommand pattern)
│   ├── commands/     # Command implementations
│   ├── utils.ts      # getCommandId helper
│   └── README.md     # 324 lines of CLI patterns
├── rest/             # REST API handlers
│   ├── handlers/     # definePluginHandler implementations
│   ├── schemas/      # Zod request/response schemas
│   └── README.md     # 358 lines of REST patterns
├── studio/           # Studio React components
│   ├── widgets/      # Widget implementations
│   └── README.md     # 443 lines of widget patterns
├── lifecycle/        # Plugin lifecycle hooks
│   ├── setup.ts      # Installation handler
│   └── README.md     # 333 lines of lifecycle patterns
├── core/             # Pure business logic
│   ├── greeting.ts   # Domain entities
│   └── README.md     # 240 lines of core patterns
└── utils/            # Shared utilities
    ├── errors.ts     # defineError pattern (219 lines)
    ├── constants.ts  # Shared constants
    └── README.md     # 348 lines of utility patterns

Streamlined error handling with defineError

import {
  TemplateError,         // Template-specific errors
  CommonError,           // Common errors (validation, not found, etc.)
  formatErrorForLogging, // For ctx.logger
  formatErrorForUser     // For user-facing messages
} from './utils/errors.js';

// Template-specific errors
throw new TemplateError.BusinessRuleViolation('Insufficient funds');
throw new TemplateError.QuotaExceeded('api_requests');

// Common errors
throw new CommonError.ValidationFailed('Email must be valid');
throw new CommonError.NotFound('User not found');

Production-ready examples

Validation with Zod:

const UserSchema = z.object({
  email: z.string().email('Invalid email'),
  age: z.number().int().min(18, 'Must be 18+')
});

export const handleCreateUser = definePluginHandler({
  schema: { input: UserSchema, output: UserResponseSchema },
  async handle(input, ctx) {
    // Input is already validated!
    const user = await createUser(input);
    return { userId: user.id };
  }
});

Type-safe contracts:

export const CommandIds = {
  HELLO: 'template:hello',
  CREATE: 'template:create'
} as const;

// Use everywhere - autocomplete + type safety
export const run = defineCommand({
  name: CommandIds.HELLO,  // ✅ No typos!
  //...
});

Multi-tenancy:

import { TenantRateLimiter } from '@kb-labs/tenant';

const limiter = new TenantRateLimiter(broker);

const result = await limiter.checkLimit(tenantId, 'api');
if (!result.allowed) {
  throw new QuotaExceededError('api', result.limit!, result.current!);
}

🧱 Architecture highlights

Canonical patterns (100% compliant)

CLI commands:

export const run = defineCommand({
  name: getCommandId('template:hello'),
  flags: {
    name: { type: 'string', default: 'World' }
  },
  async handler(ctx, argv, flags) {
    ctx.logger?.info('Command started', { name: flags.name });
    ctx.ui?.write(`Hello, ${flags.name}!\n`);
    return { ok: true, message: `Hello, ${flags.name}!`, target: flags.name };
  }
});

REST handlers:

export const handleHello = definePluginHandler({
  schema: {
    input: HelloRequestSchema,
    output: HelloResponseSchema
  },
  async handle(input, ctx) {
    ctx.logger?.info('REST handler started', { name: input.name });
    const greeting = createGreeting(input.name);
    return { message: greeting.message, target: greeting.target };
  }
});

Studio widgets:

export function HelloWidget({ data, loading, error }: HelloWidgetProps) {
  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!data) return <div>No data</div>;

  return (
    <div className="widget-container">
      <h2>Hello from Plugin Template</h2>
      <p>{data.message}</p>
    </div>
  );
}

No legacy code!

• ❌ No createConsoleLogger (deprecated)
• ❌ No DDD layers (domain/application/infrastructure)
• ❌ No path aliases (@app/, @domain/)
• ✅ 100% ctx.logger everywhere
• ✅ Pure functions in core/
• ✅ KB Labs standard folders

📦 Repository layout

kb-labs-plugin-template/
├── packages/
│   ├── plugin-template-core/    # Main plugin package
│   │   ├── src/
│   │   │   ├── cli/            # CLI commands (324 line README)
│   │   │   ├── rest/           # REST handlers (358 line README)
│   │   │   ├── studio/         # React widgets (443 line README)
│   │   │   ├── lifecycle/      # Plugin lifecycle (333 line README)
│   │   │   ├── core/           # Business logic (240 line README)
│   │   │   └── utils/          # Utilities + errors (348 line README)
│   │   ├── tests/              # Vitest tests
│   │   └── package.json        # @kb-labs/plugin-template-core
│   └── contracts/              # Type-safe contracts
├── docs/
│   ├── getting-started.md      # Setup guide
│   ├── architecture.md         # KB Labs structure
│   ├── cli-guide.md            # CLI patterns (1,395 lines of guides)
│   ├── rest-guide.md
│   ├── studio-guide.md
│   ├── examples/               # 2,500+ lines of examples
│   │   ├── validation-examples.md
│   │   ├── test-examples.md
│   │   ├── contracts-examples.md
│   │   └── multi-tenancy-examples.md
│   └── adr/
│       └── 0009-flatten-plugin-structure.md
└── scripts/                    # Sandbox scripts

🧪 Testing

# Run all tests
pnpm --filter @kb-labs/plugin-template-core run test

# Run with coverage
pnpm test -- --coverage

# Watch mode
pnpm run test:watch

Test examples included:

• ✅ CLI command tests (mocking context, validation)
• ✅ REST handler tests (Zod validation, dependencies)
• ✅ Widget tests (React Testing Library, states)
• ✅ Core logic tests (pure functions, edge cases)
• ✅ Integration tests (full flows)

See Test Examples for comprehensive testing patterns.

🔧 Scripts

| Script | Description | |--------|-------------| | pnpm build | Build all packages | | pnpm test | Run test suites | | pnpm lint | Lint codebase | | pnpm type-check | TypeScript validation | | pnpm --filter @kb-labs/plugin-template-core build | Build core package |

🎓 Learning path

New to KB Labs plugins?

1. Start here: Getting Started
2. Understand structure: Architecture
3. Add your first command: CLI Guide
4. Add validation: Validation Examples
5. Write tests: Test Examples

Building a SaaS plugin?

1. Multi-tenancy: Multi-Tenancy Examples
2. Type-safe IDs: Contracts Examples
3. REST API: REST Guide
4. Rate limiting: See multi-tenancy examples

Need specific patterns?

• Validation? → Validation Examples
• Testing? → Test Examples
• Error handling? → utils/errors.ts
• CLI commands? → CLI Guide + cli/README.md
• REST handlers? → REST Guide + rest/README.md
• React widgets? → Studio Guide + studio/README.md

🌟 Highlights

7,700+ lines of documentation

• 6 comprehensive folder READMEs (2,061 lines)
• 4 production-ready example guides (2,500 lines)
• 4 updated surface guides (1,395 lines)
• Architecture docs (ADR, REFACTORING, architecture.md)

Streamlined error handling

• defineError() pattern (87% reduction vs custom classes)
• Template-specific errors (BusinessRuleViolation, QuotaExceeded, MissingConfig)
• Common errors (ValidationFailed, NotFound, PermissionDenied, etc.)
• Formatting utilities (formatErrorForLogging, formatErrorForUser)
• Assertions (assertNotNull, assertBusinessRule)
• Error wrapping (wrapWithErrorHandling)

Production patterns

• Zod validation (advanced schemas, custom validation, type inference)
• Testing (CLI, REST, widgets, core, integration)
• Contracts (type-safe IDs, validation helpers)
• Multi-tenancy (rate limiting, quotas, data isolation)

No legacy code

• 100% ctx.logger (createConsoleLogger deprecated)
• 0 path aliases (simple imports)
• 0 DDD layers (KB Labs standard folders)
• Pure functions in core/ (no side effects)

🤝 Contributing

See CONTRIBUTING.md for:

• Coding standards
• KB Labs folder structure rules
• PR checklist
• Testing requirements

📄 License

MIT © KB Labs

Last updated: 2025-11-30 Template version: 2.0.0 (Flattened structure) Documentation: 7,735 lines Status: ✅ Production-ready gold standard

License

MIT License - see LICENSE for details.