HandlerScaffoldGen

Scaffold a TypeScript handler for concept $ARGUMENTS with typed actions, storage patterns, and a conformance test.

When to use: Use when implementing a concept handler in TypeScript. Generates a .handler.ts handler with register(), typed action methods, input extraction, storage patterns, and a conformance test file.

Design Principles

One Handler per Action: Each action in the concept spec maps to exactly one async method in the handler.
Variant Completeness: Every return variant declared in the spec must have a corresponding code path — no missing branches.
Storage Sovereignty: Each concept owns its storage exclusively — no shared databases, no cross-concept state access.
Input Extraction: Extract inputs with as casts at the top of each method. Validate required fields before processing.

Step-by-Step Process

Step 1: Register Generator

Self-register with PluginRegistry so KindSystem can track HandlerConfig → HandlerImpl transformations. Registration is also handled automatically by register-generator-kinds.sync.

Examples: Register the handler scaffold generator

const result = await handlerScaffoldGenHandler.register({}, storage);

Step 2: Preview Changes

Dry-run the generation using Emitter content-addressing to classify each output file as new, changed, or unchanged. No files are written.

Arguments: $0 conceptName (string), $1 actions (actiondef[])

Step 3: Generate Handler Implementation

Generate a handler implementation with register ( ) , typed action methods , input extraction , storage patterns , and an optional conformance test .

Arguments: $0 conceptName (string), $1 actions (actiondef[])

Checklist:

Examples: Generate a handler

clef scaffold handler --concept User --actions create,update,delete

Generate with test only

clef scaffold handler --concept Article

Step 4: Edit the Handler Implementation

Refine the generated handler: implement each action method with domain logic, extract inputs from the request with proper type casts, interact with storage using the correct relation names, and return the correct variant with all fields declared in the concept spec.

References

Handler implementation patterns

Supporting Materials

Handler implementation scaffolding walkthrough

Quick Reference

Input	Type	Purpose
conceptName	String	PascalCase concept name
actions	list ActionDef	Action signatures with params and variants
inputKind	String	KindSystem input kind
outputKind	String	KindSystem output kind
capabilities	list String	Generator capabilities

Anti-Patterns

Missing error variant

Handler doesn't return error variant on failure — caller gets an unstructured exception.

Bad:

async create(input, storage) {
  const id = crypto.randomUUID();
  await storage.put('items', id, { name: input.name });
  return { variant: 'ok', item: id };
  // Exception propagates raw if storage.put fails!
}

Good:

async create(input, storage) {
  try {
    const id = crypto.randomUUID();
    await storage.put('items', id, { name: input.name });
    return { variant: 'ok', item: id };
  } catch (err) {
    return { variant: 'error', message: String(err) };
  }
}

Validation

Generate a handler scaffold:

npx tsx cli/src/index.ts scaffold handler --concept User --actions create,update,delete

Run generated conformance test:

npx vitest run tests/user.conformance.test.ts

Run scaffold generator tests:

npx vitest run tests/scaffold-generators.test.ts

Related Skills

Skill	When to Use
`/create-concept`	Generate concept specs before implementing handlers
`/implementation-builder`	Use SchemaGen for more advanced handler generation
`/concept-validator`	Validate concept specs before generating handlers

handler-scaffold-gen