refactor: Centralize Docusaurus site processing logic

- Add central `process_site_from_path` function
- Recursively process heroscript files in `cfg` directory
- Remove duplicated site processing from `run` and `add` commands
- Respect `play` parameter from heroscript `define` block

examples/web/docusaurus_example.vsh

@@ -4,11 +4,6 @@ import freeflowuniverse.herolib.core.playcmds
 
 playcmds.run(
 	heroscript: '
-
-	!!docusaurus.config
-		name: "tfgrid_tech"
-		title: "TFGrid Tech Docs"
-
 	!!docusaurus.define
 		path_build: "/tmp/docusaurus_build"
 		path_publish: "/tmp/docusaurus_publish"
@@ -21,6 +16,7 @@ playcmds.run(
 		git_root:"/tmp/code"
 		git_reset:1
 		git_pull:1
+		play:true
 
 	!!docusaurus.build
 

lib/core/herocmds/docusaurus.v

@@ -2,9 +2,6 @@ module herocmds
 
 import freeflowuniverse.herolib.ui.console
 import freeflowuniverse.herolib.core.texttools
-import freeflowuniverse.herolib.core.playcmds
-import freeflowuniverse.herolib.core.playbook
-import freeflowuniverse.herolib.web.site
 import freeflowuniverse.herolib.web.docusaurus
 import os
 import cli { Command, Flag }
@@ -164,40 +161,9 @@ fn cmd_docusaurus_execute(cmd Command) ! {
 
 	console.print_header('Running Docusaurus for: ${source_path}')
 
-	// Process the site configuration first (excluding global includes)
-	mut combined_heroscript := ''
-	cfg_path := os.join_path(source_path, 'cfg')
-	if os.exists(cfg_path) {
-		files := os.ls(cfg_path) or { []string{} }
-		for file in files {
-			if file.ends_with('.heroscript') {
-				file_path := os.join_path(cfg_path, file)
-				content := os.read_file(file_path) or { continue }
-
-				// Skip files that contain play.include to avoid global processing
-				if content.contains('!!play.include') {
-					continue
-				}
-
-				combined_heroscript += content + '\n\n'
-			}
-		}
-	}
-
-	if combined_heroscript.len == 0 {
-		return error('No valid heroscript files found (all contained global includes)')
-	}
-
-	// Process the site configuration to get the site name
-	mut plbook := playbook.new(text: combined_heroscript)!
-	site.play(mut plbook)!
-
-	// Get the site name from the processed site configuration
-	available_sites := site.list()
-	if available_sites.len == 0 {
-		return error('No sites were created from the configuration')
-	}
-	site_name := available_sites[0] // Use the first (and likely only) site
+	// Use the centralized site processing function from docusaurus module
+	mysite := docusaurus.process_site_from_path(source_path, '')!
+	site_name := mysite.siteconfig.name
 
 	// Set up the docusaurus factory
 	docusaurus.factory_set(

lib/web/docusaurus/dsite_add.v

@@ -10,6 +10,85 @@ import freeflowuniverse.herolib.osal.core as osal
 import freeflowuniverse.herolib.core.playbook
 // import freeflowuniverse.herolib.data.doctree
 
+// Recursively process heroscript files in a directory
+fn process_heroscript_files_recursive(dir_path string) !string {
+	mut combined_heroscript := ''
+	files := os.ls(dir_path) or { return combined_heroscript }
+
+	for file in files {
+		file_path := os.join_path(dir_path, file)
+
+		if os.is_dir(file_path) {
+			// Recursively process subdirectories
+			subdir_content := process_heroscript_files_recursive(file_path)!
+			combined_heroscript += subdir_content
+		} else if file.ends_with('.heroscript') {
+			content := os.read_file(file_path) or { continue }
+
+			// Filter out only the play.include lines while keeping all other content
+			lines := content.split('\n')
+			mut filtered_lines := []string{}
+			for line in lines {
+				trimmed := line.trim_space()
+				if !trimmed.starts_with('!!play.include') {
+					filtered_lines << line
+				}
+			}
+			filtered_content := filtered_lines.join('\n')
+
+			// Only add if there's meaningful content after filtering
+			if filtered_content.trim_space().len > 0 {
+				combined_heroscript += filtered_content + '\n\n'
+			}
+		}
+	}
+	return combined_heroscript
+}
+
+// Central function to process site configuration from a path
+// This is the single point of use for all site processing logic
+// If sitename is empty, it will return the first available site
+pub fn process_site_from_path(path string, sitename string) !&site.Site {
+	console.print_debug('Processing site configuration from: ${path}')
+
+	// Process the site configuration recursively (excluding global includes)
+	combined_heroscript := process_heroscript_files_recursive('${path}/cfg')!
+	console.print_debug('Combined heroscript length: ${combined_heroscript.len} characters')
+
+	if combined_heroscript.trim_space().len == 0 {
+		return error('No valid heroscript files found in ${path}/cfg')
+	}
+
+	// Create playbook and process site configuration
+	mut plbook := playbook.new(text: combined_heroscript)!
+	console.print_debug('Created playbook with ${plbook.actions.len} actions')
+	site.play(mut plbook)!
+
+	// Check what sites were created
+	available_sites := site.list()
+	console.print_debug('Available sites after site.play(): ${available_sites}')
+
+	if available_sites.len == 0 {
+		return error('No sites were created from the configuration')
+	}
+
+	// Determine which site to return
+	target_sitename := if sitename.len == 0 {
+		console.print_debug('No specific site requested, using first available: ${available_sites[0]}')
+		available_sites[0] // Use the first (and likely only) site
+	} else {
+		console.print_debug('Looking for specific site: ${sitename}')
+		sitename
+	}
+
+	mysite := site.get(name: target_sitename) or {
+		return error('Failed to get site after playing playbook: ${target_sitename}. Available sites: ${available_sites}')
+	}
+
+	console.print_debug('Site processed successfully: ${mysite.siteconfig.name} with ${mysite.pages.len} pages')
+	return mysite
+}
+
 @[params]
 pub struct AddArgs {
 pub mut:
@@ -80,12 +159,8 @@ pub fn dsite_add(args_ AddArgs) !&DocSite {
 		if !args.play {
 			return error('Docusaurus site ${args.sitename} does not exist, please set play to true to create it.')
 		}
-		// Create new site and process config files
-		mut plbook := playbook.new(path: '${args.path}/cfg')!
-		site.play(mut plbook)!
-		mysite = site.get(name: args.sitename) or {
-			return error('Failed to get site after playing playbook: ${args.sitename}')
-		}
+		// Use the centralized site processing function
+		mysite = process_site_from_path(args.path, args.sitename)!
 	}
 
 	// Create the DocSite instance

lib/web/docusaurus/play.v

@@ -46,7 +46,7 @@ pub fn play(mut plbook PlayBook) ! {
 			git_root:     p.get_default('git_root', '')! // Make git_root optional
 			git_pull:     p.get_default_false('git_pull')
 			path_publish: p.get_default('path_publish', f.path_publish.path)!
-			play:         false // need to make sure we don't play again
+			play:         p.get_default_false('play') // Respect the play parameter from heroscript
 		)!
 		action.done = true
 	}