sea-handler-gen

name	sea-handler-gen
description	Generate SEA handlers from specifications. Creates type-safe, validated handlers with proper error handling and governance compliance.

SEA Handler Generation

Generate type-safe, validated handlers from SEA specifications. Handlers include proper error handling, validation, logging, and governance compliance.

When to Use

Invoke when:

• Spec has been updated
• New API endpoints needed
• Handlers need regeneration
• After spec validation

Usage

User invokes with:

• "Generate handlers for {context}"
• "Update handlers from spec"
• "Regenerate {context} handlers"

Claude invokes automatically:

• After spec changes are committed
• When user says "pipeline {context}"
• Before testing new API surface

Generation Process

Step 1: Load and Validate Spec

# Find spec for context
SPEC_FILE="apps/$CONTEXT/spec/context.yaml"

# Validate spec exists
if [ ! -f "$SPEC_FILE" ]; then
  echo "❌ Spec not found: $SPEC_FILE"
  exit 1
fi

# Validate YAML syntax
yq eval '.' "$SPEC_FILE" > /dev/null || exit 1

# Validate against CALM schema if applicable
calm validate "$SPEC_FILE" 2>/dev/null || true

echo "✅ Spec validated: $SPEC_FILE"

Step 2: Parse API Surface

# Extract API surface from spec
API_SURFACE=$(yq eval '.api_surface' "$SPEC_FILE")

# Extract endpoints
ENDPOINTS=$(echo "$API_SURFACE" | yq eval '.endpoints[]')

# Extract schemas
SCHEMAS=$(echo "$API_SURFACE" | yq eval '.schemas[]')

# Extract events
EVENTS=$(echo "$API_SURFACE" | yq eval '.events[]')

Step 3: Generate Handler Template

For each endpoint, generate a handler:

// src/gen/handlers/{endpoint-name}.ts
// ⚠️  GENERATED CODE - DO NOT EDIT ⚠️
// Generated from: spec/context.yaml
// Regenerate with: just pipeline {context}

import { z } from 'zod';
import { Context } from '@sprime01/sea';
import type { Request, Response } from 'express';

// Request schema (from spec)
const RequestSchema = z.object({
  // Schema from spec.api_surface.schemas
});

// Response schema
const ResponseSchema = z.object({
  // Response schema from spec
});

// Handler interface
export interface {EndpointName}Handler {
  handle(request: Request): Promise<Response>;
}

// Handler implementation
export class {EndpointName}Handler implements {EndpointName}Handler {
  constructor(
    private readonly context: Context,
    private readonly logger: Logger
  ) {}

  async handle(request: Request): Promise<Response> {
    try {
      // Validate request
      const validated = RequestSchema.parse(request.body);

      // Business logic call
      const result = await this.execute(validated);

      // Validate response
      const response = ResponseSchema.parse(result);

      return {
        status: 200,
        body: response
      };
    } catch (error) {
      this.logger.error('Handler error', { error, context: request.body });

      if (error instanceof z.ZodError) {
        return {
          status: 400,
          body: {
            error: 'Validation error',
            details: error.errors
          }
        };
      }

      return {
        status: 500,
        body: {
          error: 'Internal server error'
        }
      };
    }
  }

  private async execute(input: z.infer<typeof RequestSchema>) {
    // TODO: Implement business logic
    // This calls into the domain layer
    throw new Error('Not implemented');
  }
}

Step 4: Generate Type Definitions

// src/gen/types/{context}.ts
// ⚠️  GENERATED CODE - DO NOT EDIT ⚠️

import { z } from 'zod';

// Request schemas
export const CreateUserRequestSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
  preferences: z.record(z.unknown()).optional()
});

// Response schemas
export const UserResponseSchema = z.object({
  id: z.string().uuid(),
  name: z.string(),
  email: z.string(),
  createdAt: z.string().datetime()
});

// Domain types
export interface User {
  id: string;
  name: string;
  email: string;
  preferences: Record<string, unknown>;
  createdAt: string;
}

Step 5: Generate Express Router

// src/gen/router/{context}.ts
// ⚠️  GENERATED CODE - DO NOT EDIT ⚠️

import { Router } from 'express';
import { {EndpointName}Handler } from './handlers/{endpoint-name}';
import { Context } from '@sprime01/sea';

export function create{Context}Router(context: Context): Router {
  const router = Router();
  const handler = new {EndpointName}Handler(context, context.logger);

  // Generated from spec.api_surface.endpoints
  router.post('/api/{endpoint}', async (req, res) => {
    const response = await handler.handle(req);
    res.status(response.status).json(response.body);
  });

  return router;
}

Step 6: Generate Test Templates

// tests/handlers/{endpoint-name}.test.ts
import { describe, it, expect, beforeEach } from 'vitest';
import { {EndpointName}Handler } from '../../src/gen/handlers/{endpoint-name}';

describe('{EndpointName}Handler', () => {
  let handler: {EndpointName}Handler;

  beforeEach(() => {
    handler = new {EndpointName}Handler(
      mockContext,
      mockLogger
    );
  });

  describe('handle', () => {
    it('should validate request schema', async () => {
      const request = {
        body: { /* valid request */ }
      };

      const response = await handler.handle(request);

      expect(response.status).toBe(200);
    });

    it('should reject invalid request', async () => {
      const request = {
        body: { /* invalid request */ }
      };

      const response = await handler.handle(request);

      expect(response.status).toBe(400);
    });

    it('should handle domain errors', async () => {
      // Test error scenarios
    });
  });
});

Step 7: Update Generated Zone Guard

Add .SEA-PROTECTED marker to all generated files:

/**
 * ⚠️  GENERATED CODE - DO NOT EDIT ⚠️
 *
 * This file is automatically generated from:
 *   apps/{context}/spec/context.yaml
 *
 * To modify this handler:
 * 1. Edit the spec file
 * 2. Run: just pipeline {context}
 * 3. Handlers will be regenerated
 *
 * Manual edits will be overwritten.
 *
 * Generated at: {timestamp}
 * Spec version: {version}
 */

Handler Patterns

CRUD Handlers

// Create
export class Create{Entity}Handler {
  async handle(request: Create{Entity}Request): Promise<{Entity}Response> {
    const entity = await this.domain.create(request.body);
    return this.serializer.serialize(entity);
  }
}

// Read
export class Read{Entity}Handler {
  async handle(request: Read{Entity}Request): Promise<{Entity}Response> {
    const entity = await this.domain.findById(request.params.id);
    if (!entity) {
      throw new NotFoundError('Entity not found');
    }
    return this.serializer.serialize(entity);
  }
}

// Update
export class Update{Entity}Handler {
  async handle(request: Update{Entity}Request): Promise<{Entity}Response> {
    const entity = await this.domain.update(request.params.id, request.body);
    return this.serializer.serialize(entity);
  }
}

// Delete
export class Delete{Entity}Handler {
  async handle(request: Delete{Entity}Request): Promise<void> {
    await this.domain.delete(request.params.id);
  }
}

Event Handlers

export class {EventName}Handler {
  async handle(event: {EventName}Event): Promise<void> {
    // Validate event schema
    const validated = {EventName}Schema.parse(event);

    // Process event
    await this.domain.processEvent(validated);

    // Emit downstream events if applicable
    await this.eventBus.publish({
      type: '{EventName}Processed',
      payload: validated
    });
  }
}

Validation

After generation, validate:

# TypeScript compilation
tsc --noEmit

# Linting
eslint src/gen/

# Schema validation
# (validate generated schemas match spec)

# Test compilation
vitest --run tests/

Integration

• Integrates with sea-generator-first for pipeline execution
• Integrates with spec-guardian for generated zone protection
• Integrates with governance-validation for CALM compliance
• Integrates with zod for runtime validation

Output

After generation:

## Handlers Generated

**Context**: {context}
**Spec**: spec/context.yaml
**Version**: {version}

### Generated Files
- Handlers: {count}
- Types: {count}
- Router: 1
- Tests: {count}

### Handlers
- {endpoint1}: Create{Entity}Handler
- {endpoint2}: Read{Entity}Handler
- {endpoint3}: Update{Entity}Handler
- {endpoint4}: Delete{Entity}Handler

### Validation
✅ TypeScript compilation passed
✅ All schemas validated
✅ Tests templates generated

### Next Steps
1. Implement business logic in domain layer
2. Run tests: pnpm test
3. Test API surface: pnpm test:e2e