Layer 5: Action Handler Layer

Semantic Action Routing

Action Handlers route semantic actions (CREATE_FILE, ENHANCE_FILE, etc.) to appropriate execution logic.

Purpose

Provide semantic abstractions over low-level file operations.

Blueprint authors write:

{ type: 'ENHANCE_FILE', path: 'layout.tsx', modifier: 'jsx-children-wrapper' }

Not:

// Low-level operations blueprint authors DON'T write:
const ast = parseFile('layout.tsx');
const jsxElement = findJSXElement(ast);
modifyChildren(jsxElement);
writeFile('layout.tsx', serialize(ast));

Action Handlers

File Location

src/core/services/execution/blueprint/action-handlers/

Available Handlers

create-file-handler.ts - CREATE_FILE action
enhance-file-handler.ts - ENHANCE_FILE action
install-packages-handler.ts - INSTALL_PACKAGES action
add-script-handler.ts - ADD_SCRIPT action
add-env-var-handler.ts - ADD_ENV_VAR action
add-dependency-handler.ts - ADD_DEPENDENCY action
run-command-handler.ts - RUN_COMMAND action

Registry Pattern

// src/core/services/execution/blueprint/action-handlers/action-handler-registry.ts
export class ActionHandlerRegistry {
  private handlers: Map<string, ActionHandler>;
 
  constructor(modifierRegistry: ModifierRegistry) {
    this.handlers = new Map();
    this.registerHandlers(modifierRegistry);
  }
 
  async handleAction(
    action: BlueprintAction,
    context: ProjectContext,
    projectRoot: string,
    vfs: VirtualFileSystem
  ): Promise<ActionResult> {
    
    const handler = this.handlers.get(action.type);
    
    if (!handler) {
      return { success: false, error: `Unknown action type: ${action.type}` };
    }
    
    return await handler.handle(action, context, projectRoot, vfs);
  }
}

Next: Complete Blueprint Actions Reference →

Layer 4: Executor Layer 6: Modifiers