Headless mode (#124)

Implemented headless mode, decoupled renderer from TUI.

Author: VitjanZ

docs/plain2code_cli.md

@@ -1,16 +1,18 @@
 # Plain2Code CLI Reference
 
 ```text
-usage: generate_cli.py [-h] [--verbose] [--base-folder BASE_FOLDER] [--build-folder BUILD_FOLDER] [--log-to-file | --no-log-to-file] [--log-file-name LOG_FILE_NAME] [--config-name CONFIG_NAME] [--render-range RENDER_RANGE | --render-from RENDER_FROM] [--force-render]
-                       [--unittests-script UNITTESTS_SCRIPT] [--conformance-tests-folder CONFORMANCE_TESTS_FOLDER] [--conformance-tests-script CONFORMANCE_TESTS_SCRIPT] [--prepare-environment-script PREPARE_ENVIRONMENT_SCRIPT] [--api [API]] [--api-key API_KEY]
-                       [--full-plain] [--dry-run] [--replay-with REPLAY_WITH] [--template-dir TEMPLATE_DIR] [--copy-build] [--build-dest BUILD_DEST] [--copy-conformance-tests] [--conformance-tests-dest CONFORMANCE_TESTS_DEST] [--render-machine-graph]
-                       [--logging-config-path]
+usage: generate_cli.py [-h] [--verbose] [--base-folder BASE_FOLDER] [--build-folder BUILD_FOLDER] [--log-to-file | --no-log-to-file] [--log-file-name LOG_FILE_NAME] [--config-name CONFIG_NAME]
+                       [--render-range RENDER_RANGE | --render-from RENDER_FROM] [--force-render] [--unittests-script UNITTESTS_SCRIPT] [--conformance-tests-folder CONFORMANCE_TESTS_FOLDER]
+                       [--conformance-tests-script CONFORMANCE_TESTS_SCRIPT] [--prepare-environment-script PREPARE_ENVIRONMENT_SCRIPT] [--test-script-timeout TEST_SCRIPT_TIMEOUT] [--api [API]] [--api-key API_KEY]
+                       [--full-plain] [--dry-run] [--replay-with REPLAY_WITH] [--template-dir TEMPLATE_DIR] [--copy-build] [--build-dest BUILD_DEST] [--copy-conformance-tests]
+                       [--conformance-tests-dest CONFORMANCE_TESTS_DEST] [--render-machine-graph] [--logging-config-path] [--headless]
                        filename
 
 Render plain code to target code.
 
 positional arguments:
-  filename              Path to the plain file to render. The directory containing this file has highest precedence for template loading, so you can place custom templates here to override the defaults. See --template-dir for more details about template loading.
+  filename              Path to the plain file to render. The directory containing this file has highest precedence for template loading, so you can place custom templates here to override the defaults. See --template-dir
+                        for more details about template loading.
 
 options:
   -h, --help            show this help message and exit
@@ -20,41 +22,48 @@ options:
   --build-folder BUILD_FOLDER
                         Folder for build files
   --log-to-file, --no-log-to-file
-                        Enable logging to a file. Defaults to True. Use --no-log-to-file to disable.
+                        Enable logging to a file. Defaults to True. Set to False to disable.
   --log-file-name LOG_FILE_NAME
-                        Name of the log file. Defaults to 'codeplain.log'.Always resolved relative to the plain file directory.If file on this path already exists, it will be overwritten by the current logs.
+                        Name of the log file. Defaults to 'codeplain.log'.Always resolved relative to the plain file directory.If file on this path already exists, the already existing log file will be overwritten by the
+                        current logs.
   --render-range RENDER_RANGE
-                        Specify a range of functional requirements to render (e.g. '1.1,2.3'). Use comma to separate start and end IDs. If only one ID is provided, only that requirement is rendered. Range is inclusive of both start and end IDs.
+                        Specify a range of functional requirements to render (e.g. `1` , `2`, `3`). Use comma to separate start and end IDs. If only one ID is provided, only that requirement is rendered. Range is
+                        inclusive of both start and end IDs.
   --render-from RENDER_FROM
-                        Continue generation starting from this specific functional requirement (e.g. '2.1'). The requirement with this ID will be included in the output. The ID must match one of the functional requirements in your plain file.
+                        Continue generation starting from this specific functional requirement (e.g. `2`). The requirement with this ID will be included in the output. The ID must match one of the functional requirements
+                        in your plain file.
   --force-render        Force re-render of all the required modules.
   --unittests-script UNITTESTS_SCRIPT
                         Shell script to run unit tests on generated code. Receives the build folder path as its first argument (default: 'plain_modules').
   --conformance-tests-folder CONFORMANCE_TESTS_FOLDER
                         Folder for conformance test files
   --conformance-tests-script CONFORMANCE_TESTS_SCRIPT
-                        Path to conformance tests shell script. The script should accept two arguments: 1) First argument: path to a folder (e.g. 'plain_modules/module_name') containing generated source code, 2) Second argument: path to a subfolder of the conformance
-                        tests folder (e.g. 'conformance_tests/subfoldername') containing test files.
+                        Path to conformance tests shell script. Every conformance test script should accept two arguments: 1) Path to a folder (e.g. `plain_modules/module_name`) containing generated source code, 2) Path
+                        to a subfolder of the conformance tests folder (e.g. `conformance_tests/subfoldername`) containing test files.
   --prepare-environment-script PREPARE_ENVIRONMENT_SCRIPT
-                        Path to a shell script that prepares the testing environment. The script should accept the build folder path as its first argument (default: 'plain_modules').
+                        Path to a shell script that prepares the testing environment. The script should accept the source code folder path as its first argument.
+  --test-script-timeout TEST_SCRIPT_TIMEOUT
+                        Timeout for test scripts in seconds. If not provided, the default timeout of 120 seconds is used.
   --api [API]           Alternative base URL for the API. Default: `https://api.codeplain.ai`
-  --api-key API_KEY     API key used to access the API. If not provided, the CODEPLAIN_API_KEY environment variable is used.
-  --full-plain          Display the complete plain specification before code generation. This shows your plain file with any included template content expanded. Useful for understanding what content is being processed.
-  --dry-run             Preview of what Codeplain would do without actually making any changes.
+  --api-key API_KEY     API key used to access the API. If not provided, the `CODEPLAIN_API_KEY` environment variable is used.
+  --full-plain          Full preview ***plain specification before code generation.Use when you want to preview context of all ***plain primitives that are going to be included in order to render the given module.
+  --dry-run             Dry run preview of the code generation (without actually making any changes).
   --replay-with REPLAY_WITH
   --template-dir TEMPLATE_DIR
-                        Path to a custom template directory. Templates are searched in the following order: 1) directory containing the plain file, 2) this custom template directory (if provided), 3) built-in standard_template_library directory
-  --copy-build          If set, copy the build folder to `--build-dest` after every successful rendering.
+                        Path to a custom template directory. Templates are searched in the following order: 1) Directory containing the plain file, 2) Custom template directory (if provided through this argument), 3)
+                        Built-in standard_template_library directory
+  --copy-build          If set, copy the rendered contents of code in `--base-folder` folder to `--build-dest` folder after successful rendering.
   --build-dest BUILD_DEST
-                        Target folder to copy build output to (used only if --copy-build is set).
+                        Target folder to copy rendered contents of code to (used only if --copy-build is set).
   --copy-conformance-tests
-                        If set, copy the conformance tests folder to `--conformance-tests-dest` after every successful rendering. Requires --conformance-tests-script.
+                        If set, copy the conformance tests of code in `--conformance-tests-folder` folder to `--conformance-tests-dest` folder successful rendering. Requires --conformance-tests-script.
   --conformance-tests-dest CONFORMANCE_TESTS_DEST
-                        Target folder to copy conformance tests output to (used only if --copy-conformance-tests is set).
+                        Target folder to copy conformance tests of code to (used only if --copy-conformance-tests is set).
   --render-machine-graph
                         If set, render the state machine graph.
   --logging-config-path
                         Path to the logging configuration file.
+  --headless            Run in headless mode: no TUI, no terminal output except a single render-started message. All logs are written to the log file.
 
 configuration:
   --config-name CONFIG_NAME

event_bus.py

@@ -7,26 +7,11 @@
 class EventBus:
     def __init__(self):
         self._listeners: defaultdict[Type[BaseEvent], list[Callable[[Any], None]]] = defaultdict(list)
-        self._main_thread_callback: Callable[[Callable], None] | None = None
-        self._ready_callbacks: list[Callable[[], None]] = []
-
-    def register_main_thread_callback(self, fn: Callable[[Callable], None]):
-        """Set the function to call listeners from the main thread (e.g., Textual app.call_from_thread)."""
-        self._main_thread_callback = fn
-
-        # Notify anyone waiting for the event bus to be ready
-        for callback in self._ready_callbacks:
-            callback()
-        self._ready_callbacks.clear()
-
-    def on_ready(self, callback: Callable[[], None]):
-        """Register a callback to be called when the event bus is ready."""
-        if self._main_thread_callback:
-            # Already ready, call immediately
-            callback()
-        else:
-            # Not ready yet, queue it
-            self._ready_callbacks.append(callback)
+        self._dispatch_wrapper: Callable[[Callable], None] | None = None
+
+    def register_dispatch_wrapper(self, fn: Callable[[Callable], None]):
+        """Set a wrapper for dispatching listeners (e.g., Textual's app.call_from_thread)."""
+        self._dispatch_wrapper = fn
 
     def subscribe(self, event_type: Type[BaseEvent], listener: Callable[[Any], None]):
         """Registers a listener for a specific event type."""
@@ -39,7 +24,7 @@ def _dispatch():
             for listener in self._listeners[type(event)]:
                 listener(event)
 
-        if not self._main_thread_callback:
-            raise RuntimeError("No main thread callback set. Call register_main_thread_callback() first.")
-
-        self._main_thread_callback(_dispatch)
+        if self._dispatch_wrapper:
+            self._dispatch_wrapper(_dispatch)
+        else:
+            _dispatch()

plain2code.py

@@ -3,6 +3,7 @@
 import logging.config
 import os
 import sys
+import threading
 from pathlib import Path
 from typing import Optional
 
@@ -18,6 +19,7 @@
 from module_renderer import ModuleRenderer
 from plain2code_arguments import parse_arguments
 from plain2code_console import console
+from plain2code_events import RenderFailed
 from plain2code_exceptions import (
     ConflictingRequirements,
     CreditBalanceTooLow,
@@ -122,6 +124,7 @@ def setup_logging(
     log_file_name: str,
     plain_file_path: Optional[str],
     render_id: str,
+    headless: bool = False,
 ):
     # Set default level to INFO for everything not explicitly configured
     logging.getLogger().setLevel(logging.INFO)
@@ -162,10 +165,12 @@ def setup_logging(
     for h in root_logger.handlers[:]:
         root_logger.removeHandler(h)
 
-    handler = TuiLoggingHandler(event_bus)
     formatter = IndentedFormatter("%(levelname)s:%(name)s:%(message)s")
-    handler.setFormatter(formatter)
-    root_logger.addHandler(handler)
+
+    if not headless:
+        handler = TuiLoggingHandler(event_bus)
+        handler.setFormatter(formatter)
+        root_logger.addHandler(handler)
 
     if log_to_file and log_file_path:
         try:
@@ -232,24 +237,36 @@ def render(args, run_state: RunState, event_bus: EventBus):  # noqa: C901
         event_bus,
     )
 
-    app = Plain2CodeTUI(
-        event_bus=event_bus,
-        worker_fun=module_renderer.render_module,
-        render_id=run_state.render_id,
-        unittests_script=args.unittests_script,
-        conformance_tests_script=args.conformance_tests_script,
-        prepare_environment_script=args.prepare_environment_script,
-        state_machine_version=system_config.client_version,
-        css_path="styles.css",
-    )
-    result = app.run()
+    render_error: list[Exception] = []
 
-    # If the app exited due to a worker error, re-raise it here
-    # so it hits the exception handlers in main()
-    if isinstance(result, Exception):
-        raise result
+    def run_render():
+        try:
+            module_renderer.render_module()
+        except Exception as e:
+            render_error.append(e)
+            event_bus.publish(RenderFailed(error_message=str(e)))
 
-    return
+    if args.headless:
+        print(f"Render started. Render ID: {run_state.render_id}")
+        module_renderer.render_module()
+        return
+    else:
+        render_thread = threading.Thread(target=run_render, daemon=True)
+        app = Plain2CodeTUI(
+            event_bus=event_bus,
+            on_ready=render_thread.start,
+            render_id=run_state.render_id,
+            unittests_script=args.unittests_script,
+            conformance_tests_script=args.conformance_tests_script,
+            prepare_environment_script=args.prepare_environment_script,
+            state_machine_version=system_config.client_version,
+            css_path="styles.css",
+        )
+        app.run()
+        render_thread.join(timeout=1)
+
+    if render_error:
+        raise render_error[0]
 
 
 def main():  # noqa: C901
@@ -285,7 +302,13 @@ def main():  # noqa: C901
 
     run_state = RunState(spec_filename=args.filename, replay_with=args.replay_with)
 
-    setup_logging(args, event_bus, args.log_to_file, args.log_file_name, args.filename, run_state.render_id)
+    if args.headless:
+        # Suppress Rich console output.
+        console.quiet = True
+
+    setup_logging(
+        args, event_bus, args.log_to_file, args.log_file_name, args.filename, run_state.render_id, args.headless
+    )
 
     exc_info = None
     try:

plain2code_arguments.py

@@ -288,6 +288,14 @@ def create_parser():
         help="Path to the logging configuration file.",
     )
 
+    parser.add_argument(
+        "--headless",
+        action="store_true",
+        default=False,
+        help="Run in headless mode: no TUI, no terminal output except a single render-started message. "
+        "All logs are written to the log file.",
+    )
+
     return parser
 
 

plain2code_logger.py

@@ -40,15 +40,10 @@ class TuiLoggingHandler(logging.Handler):
     def __init__(self, event_bus: EventBus):
         super().__init__()
         self.event_bus = event_bus
-        self._buffer = []
-        self.start_time = time.time()  # Record start time for offset calculation
-
-        # Register to be notified when event bus is ready
-        self.event_bus.on_ready(self._flush_buffer)
+        self.start_time = time.time()
 
     def emit(self, record):
         try:
-            # Extract structured data from the log record
             offset_seconds = record.created - self.start_time
             minutes = int(offset_seconds // 60)
             seconds = int(offset_seconds % 60)
@@ -60,28 +55,14 @@ def emit(self, record):
                 message=record.getMessage(),
                 timestamp=timestamp,
             )
-
-            # Try to publish, fall back to buffering if not ready
-            if self.event_bus._main_thread_callback:
-                self.event_bus.publish(event)
-            else:
-                self._buffer.append(event)
+            self.event_bus.publish(event)
         except RuntimeError:
             # We're going to get this crash after the TUI app is closed (forcefully).
             # NOTE: This should be more thought out.
             pass
         except Exception:
             self.handleError(record)
 
-    def _flush_buffer(self):
-        """Flush buffered log messages to the event bus."""
-        for event in self._buffer:
-            try:
-                self.event_bus.publish(event)
-            except Exception:
-                pass
-        self._buffer.clear()
-
 
 class CrashLogHandler(logging.Handler):
     def __init__(self):