handler-scaffold-gen（处理程序脚手架生成）

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 typed action methods, input extraction, and storage patterns. Defaults to functional (StorageProgram) style; pass style = imperative for the imperative fallback. Optionally generates a conformance test.

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

Checklist:

• Handler export name follows convention (camelCase + 'Handler')?
• register() returns correct name, inputKind, outputKind?
• Each action extracts input parameters with correct types?
• Each action returns all declared variants?
• Storage operations use correct relation names?
• Error handling catches and wraps exceptions?
• Conformance test covers register() and each action?
• All files written through Emitter (not directly to disk)?
• Source provenance attached to each file?
• Generation step recorded in GenerationPlan?

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

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