Blueprint Actions

High-Level Semantic Operations

Blueprint Actions are the semantic building blocks that blueprint authors use to generate code. They are high-level operations that abstract away implementation complexity.

Philosophy: Semantic Over Primitive

The Problem with Primitives

Traditional code generators use low-level operations:

// LOW-LEVEL (bad for blueprint authors)
const ast = parseTypeScript('src/file.ts');
const importDecl = createImportDeclaration('QueryProvider', '@/lib/query');
ast.body.unshift(importDecl);
writeFile('src/file.ts', serializeAST(ast));

Problems:

• ❌ Blueprint authors need AST knowledge
• ❌ Brittle and error-prone
• ❌ Hard to maintain
• ❌ Inconsistent across blueprints

The Architech Approach: Semantic Actions

// HIGH-LEVEL (good for blueprint authors)
{
  type: 'ENHANCE_FILE',
  path: 'src/file.ts',
  modifier: 'ts-module-enhancer',
  params: {
    importsToAdd: [
      { name: 'QueryProvider', from: '@/lib/query' }
    ]
  }
}

Benefits:

• ✅ Intent-driven (what to do, not how)
• ✅ Simple API for blueprint authors
• ✅ Complexity hidden in CLI
• ✅ Consistent across all blueprints

Core Principle

Complexity must be in the CLI, never in the blueprint.

Blueprint authors focus on what to generate. The CLI handles how to safely execute it.

Action Categories

1. File Creation Actions

• CREATE_FILE - Create new files

2. File Modification Actions

• ENHANCE_FILE - Modify files using modifiers
• APPEND_TO_FILE - Append content
• PREPEND_TO_FILE - Prepend content

3. Dependency Actions

• INSTALL_PACKAGES - Install npm packages
• ADD_DEPENDENCY - Add to package.json
• ADD_SCRIPT - Add npm script

4. Configuration Actions

• ADD_ENV_VAR - Add environment variable
• MERGE_JSON - Deep merge JSON files

5. Command Actions

• RUN_COMMAND - Execute CLI commands

Actions → Modifiers → AST

The Execution Chain

Blueprint Action (semantic)
      ↓
Action Handler (routes)
      ↓
Modifier (if complex operation)
      ↓
AST Manipulation (ts-morph)
      ↓
VFS Write (in-memory)

Example: ENHANCE_FILE Flow

// 1. Blueprint author writes (semantic):
{
  type: 'ENHANCE_FILE',
  path: 'src/app/layout.tsx',
  modifier: 'jsx-children-wrapper',
  params: { wrapperComponent: 'QueryProvider' }
}
 
// 2. Action handler routes:
const modifier = modifierRegistry.get('jsx-children-wrapper');
await modifier.execute(path, params, context, vfs);
 
// 3. Modifier uses AST:
const sourceFile = project.createSourceFile(path, content);
// ... AST manipulation ...
const modified = sourceFile.getFullText();
 
// 4. VFS write:
vfs.writeFile(path, modified);

Blueprint author never touches AST!

Documentation Structure

Action Reference →

Complete API for all actions with examples.

Modifiers →

Deep dive into the modifier system and AST manipulation.

Best Practices →

Patterns and anti-patterns for blueprint authors.

Advanced Patterns →

forEach loops, conditional actions, dynamic blueprints.

For Marketplace Module Authors

If you're creating adapters, connectors, or features for a marketplace, this section is your complete reference for blueprint actions.

Start here: Action Reference →

Actions are the language blueprints speak. Master them to master The Architech.