Skip to content

Latest commit

 

History

History
155 lines (110 loc) · 4.05 KB

REFACTORING_SUMMARY.md

File metadata and controls

155 lines (110 loc) · 4.05 KB

Blueprint Flow Refactoring Summary

Overview

Refactored the blueprint flow system to use a Step Type Registry Pattern for better maintainability and easier updates to TOML files, CLI flows, and validations.

Key Changes

1. New Architecture Components

Step Type Registry (src/services/step-types/)

  • Base Step Type (base-step.ts): Abstract class with shared validation logic
  • Registry (registry.ts): Central registry for step type definitions
  • Individual Step Modules: One file per step type
    • info-step.ts - Display information
    • navigate-step.ts - Direct users to URLs
    • input-step.ts - Capture user input
    • choice-step.ts - Present selection options
    • confirm-step.ts - Ask for confirmation
    • show-commands-step.ts - Display commands
    • ai-prompt-step.ts - AI prompt integration

2. Simplified Core Services

FlowExecutor (flow-executor.ts)

Before: 35-line switch statement handling each step type

switch (step.type) {
  case "info": return await StepHandlers.executeInfoStep(...);
  case "navigate": return await StepHandlers.executeNavigateStep(...);
  // ... 7 cases
}

After: Single line using registry

return await stepRegistry.execute(step, this.context);

BlueprintValidator (blueprint-validator.ts)

Before: 65-line switch statement for validation

switch (step.type) {
  case "info":
    if (!step.markdown) { errors.push(...) }
  // ... 7 cases
}

After: Single line delegation

return stepRegistry.validate(step);

3. Benefits

✅ Single Source of Truth

Each step type now contains ALL its logic in one place:

  • Required/optional fields
  • Validation rules
  • Execution logic

✅ Easy to Add New Step Types

  1. Create new file in step-types/ (e.g., webhook-step.ts)
  2. Extend BaseStepType
  3. Register it in index.ts
  4. Update JSON schema

✅ Easy to Modify Existing Steps

  • Change validation? Update the step type's requiredFields or customValidation()
  • Change behavior? Update the step type's execute() method
  • All logic is colocated

✅ Better Testability

Each step type can be tested independently without complex mocking

✅ TOML Updates Made Simple

To update TOML schema:

  1. Modify the step type definition (e.g., add new field to requiredFields)
  2. Update JSON schema in spec/blueprint-schema.json
  3. No need to touch switch statements

Example: Adding a New Step Type

// src/services/step-types/webhook-step.ts
export class WebhookStepType extends BaseStepType {
  type = "webhook" as const;
  requiredFields = ["url", "method"];
  optionalFields = ["headers", "body"];

  async execute(step: FlowStep, context: VariableContext): Promise<StepResult> {
    // Implementation here
  }
}

export const webhookStepType = new WebhookStepType();

Then register it:

// src/services/step-types/index.ts
import { webhookStepType } from "./webhook-step.js";

stepRegistry.registerAll([
  // ... existing types
  webhookStepType,
]);

Files Modified

  • ✏️ src/services/flow-executor.ts - Simplified to use registry
  • ✏️ src/services/blueprint-validator.ts - Simplified to use registry

Files Created

  • ✨ src/services/step-types/base-step.ts
  • ✨ src/services/step-types/registry.ts
  • ✨ src/services/step-types/info-step.ts
  • ✨ src/services/step-types/navigate-step.ts
  • ✨ src/services/step-types/input-step.ts
  • ✨ src/services/step-types/choice-step.ts
  • ✨ src/services/step-types/confirm-step.ts
  • ✨ src/services/step-types/show-commands-step.ts
  • ✨ src/services/step-types/ai-prompt-step.ts
  • ✨ src/services/step-types/index.ts

Backward Compatibility

✅ All existing TOML blueprints work without changes ✅ All existing functionality preserved ✅ Build passes successfully

Next Steps (Optional)

  1. Generate JSON schema automatically from step type registry
  2. Add unit tests for each step type
  3. Create TOML validation CLI command using registry
  4. Add step type documentation generator