Hero Generator Module

Code generator for creating V modules in the HeroLib context.

Architecture

lib/core/generator/
└── hero_generator/           # Main generator module
    ├── model.v               # Types: Cat, ModuleMeta, GenerateArgs
    ├── generator.v           # prepare_meta() - prepares metadata
    ├── heroscript.v          # args_get(), create_heroscript()
    ├── interactive.v         # prompt_interactive() - interactive mode
    ├── scanner.v             # scan_modules(), register_in_factory()
    ├── installer/            # Installer-specific generator
    │   ├── generate.v        # generate_exec()
    │   └── templates/        # Installer templates
    ├── client/               # Client-specific generator
    │   ├── generate.v        # generate_exec()
    │   └── templates/        # Client templates
    └── k8sapp/               # K8s app-specific generator
        ├── generate.v        # generate_exec()
        └── templates/        # K8sapp templates

Flow

CLI (herocmds/generator.v)
    │
    ├── Non-interactive mode:
    │   1. Parse flags
    │   2. hero_generator.prepare_meta() → creates .heroscript, returns ModuleMeta
    │   3. run_generator() → routes to type-specific generator
    │
    └── Interactive mode:
        1. hero_generator.prompt_interactive() → prompts user, returns ModuleMeta
        2. run_generator() → routes to type-specific generator

run_generator(meta, reset):
    match meta.cat:
        .installer → installer.generate_exec()
        .client    → client.generate_exec()
        .k8sapp    → k8sapp.generate_exec()

    register_in_factory(meta)  # Auto-registers module in factory.v

Usage

##hero generate installer -name my_installer -path lib/installers/my_installer

##hero generate client -name my_client -path lib/clients/my_client

##hero generate k8sapp -name my_k8app -path lib/k8_apps/my_k8app

##hero generate installer -path lib/installers/my_installer -i

##hero generate scan -g

Module Types

Installer

• Lifecycle management: install, start, stop, restart, destroy
• Startup manager integration
• Optional templates for configuration files

Client

• Factory pattern with Redis-based persistence
• CRUD operations: new, get, set, delete, exists, list
• Instance methods: save, reload
• No lifecycle management

K8sapp

• Kubernetes deployment templates
• Deploy/destroy operations
• Always includes templates directory

Automatic Registration

When a module is generated, it is automatically registered in lib/core/playcmds/factory.v:1. An import statement is added2. A module.play(mut plbook)! call is inserted before the empty check

This allows the module to be immediately usable via HeroScript without manual registration.

fn args_get(path string) !ModuleMeta

args_get reads the .heroscript file and returns ModuleMeta

fn create_heroscript(args ModuleMeta) !

create_heroscript generates the .heroscript file for a module

fn get_meta(path string) !ModuleMeta

get_meta returns the ModuleMeta for a given path by parsing .heroscript

fn name_to_classname(name string) string

name_to_classname converts a snake_case name to PascalCase class name e.g., "my_installer" -> "MyInstaller", "api_client" -> "ApiClient"

fn prepare_meta(args_ GenerateArgs) !ModuleMeta

prepare_meta prepares the ModuleMeta from GenerateArgs and creates .heroscript Returns the meta for the caller to route to the appropriate generator

fn prompt_interactive(args_ GenerateArgs) !InteractiveResult

prompt_interactive runs the interactive prompt-based generator Returns the meta and whether the user wants to proceed

fn register_in_factory(meta ModuleMeta) !

register_in_factory adds a module's import and play() call to factory.v This is called when generating a new module so it's automatically registered

fn scan_modules(args_ ScannerArgs) !ScanResult

scan_modules finds all .heroscript files and returns their metadata The caller is responsible for routing to the appropriate generators

enum Cat {
	installer
	client
	k8sapp
}

Cat represents the category of module to generate

struct GenerateArgs {
pub mut:
	path           string
	reset          bool
	force          bool // deprecated: use interactive instead
	name           string
	classname      string
	title          string
	singleton      bool
	templates      bool
	hasconfig      bool = true
	default        bool = true
	startupmanager bool = true
	build          bool
	cat            Cat = .installer
	interactive    bool // if true, use interactive mode with prompts
}

GenerateArgs contains the arguments for module generation

fn (args GenerateArgs) to_meta() ModuleMeta

to_meta converts GenerateArgs to ModuleMeta

struct InteractiveResult {
pub:
	meta         ModuleMeta
	run_it       bool // true if user wants to run generation
	use_existing bool // true if using existing .heroscript
}

InteractiveResult holds the result of interactive prompts

struct ModuleMeta {
pub mut:
	name                string // e.g. docusaurus
	classname           string // e.g. Docusaurus
	title               string // e.g. Docusaurus Website Generator
	singleton           bool   // if true, only one instance can exist
	templates           bool   // if true, include template files
	hasconfig           bool = true // if true, module has a config struct
	default             bool = true // if true, create default instance on new()
	startupmanager      bool = true // if true, use startup manager for lifecycle
	build               bool // if true, include build/compilation support
	cat                 Cat = .installer // category of module
	path                string // e.g. /home/user/code/mymodule
	module_path         string // e.g. incubaid.herolib.web.docusaurus
	active              bool = true // if false then we skip generation
	supported_platforms []string // only relevant for installers for now
	play_name           string   // e.g. docusaurus is what we look for
}

ModuleMeta contains metadata about a module to be generated

fn (mut m ModuleMeta) check() !

check validates the ModuleMeta and populates the module_path

fn (args ModuleMeta) platform_check_str() string

platform_check_str returns a V condition string for platform checks

struct ScanResult {
pub:
	modules      []ModuleMeta
	generate_all bool // true if scanning from herolib root
}

ScanResult holds the result of scanning for .heroscript files

struct ScannerArgs {
pub mut:
	path string
}