Decouple le bootstrap CLI de Qt

Evite d'initialiser Qt au demarrage de la CLI lorsque la commande demandee est purement headless, afin de permettre l'execution de l'outil sans charger PySide6 pour les cas non GUI.

Introduit une decision explicite via should_enable_qt dans le runtime, puis branche l'entrypoint pour n'activer les metadonnees et handlers Qt que lorsque la commande cible ouvre effectivement une interface graphique.

Supprime egalement les imports module-level qui tiraient EngineLoader et les launchers GUI trop tot dans click_app, fallback et la CLI dediee, en les remplacant par des helpers lazy centralises dans cli/lazy_ops.py.

Le chemin headless couvre desormais correctement les commandes telles que --help, --version, --info, --cli, unload, engine ..., ainsi que engines --dry-run sans bootstrap Qt prealable.

Ajoute enfin un test cible pour verifier la decision d'activation de Qt et garantir que les modules CLI principaux restent importables sans effet de bord GUI immediat.

Author: raidos23

cli/click_app.py

@@ -6,13 +6,13 @@
 from pathlib import Path
 import sys
 
-from EngineLoader import unload_all
-
 from .dedicated import run_dedicated_cli
-from .launchers import (
-    launch_bcasl_standalone,
-    launch_engines_only_standalone,
-    launch_main_application,
+from .lazy_ops import (
+    available_engine_ids,
+    launch_bcasl_gui,
+    launch_engines_gui,
+    launch_main_gui,
+    unload_all_engines,
 )
 from .output import error, info, plain, warn
 from .system_info import print_system_info
@@ -109,7 +109,7 @@ def cli(
             ctx.exit(run_dedicated_cli(app_version))
 
         if unload_engines_flag:
-            result = unload_all()
+            result = unload_all_engines()
             if result["status"] == "success":
                 info(f"{result['message']}")
                 if result["unloaded"]:
@@ -137,7 +137,7 @@ def cli(
 
         if ctx.invoked_subcommand is None:
             ctx.exit(
-                launch_main_application(
+                launch_main_gui(
                     no_splash=ctx.obj.get("no_splash", False),
                     ide_gui=ctx.obj.get("ide_gui", False),
                     classic_gui=ctx.obj.get("classic_gui", False),
@@ -166,7 +166,7 @@ def bcasl(workspace):
                     error(f"Failed to create directory: {exc}")
                     sys.exit(1)
 
-        sys.exit(launch_bcasl_standalone(workspace_dir))
+        sys.exit(launch_bcasl_gui(workspace_dir))
 
     @cli.command(context_settings=dict(help_option_names=["-h", "--help"]))
     @click.argument("workspace", required=False, type=click.Path(exists=False))
@@ -206,23 +206,21 @@ def engines(workspace, dry_run, language, theme):
                     sys.exit(1)
 
         if dry_run:
-            from EngineLoader import available_engines
-
-            engines = available_engines()
+            engines = available_engine_ids()
             plain(f"Available engines ({len(engines)}):")
             for eid in engines:
                 plain(f"  • {eid}")
             sys.exit(0)
 
-        sys.exit(launch_engines_only_standalone(workspace_dir))
+        sys.exit(launch_engines_gui(workspace_dir))
 
     @cli.command(context_settings=dict(help_option_names=["-h", "--help"]))
     def main_app():
         """Launch the main PyCompiler ARK application."""
         ctx = click.get_current_context(silent=True)
         ctx_obj = ctx.obj if ctx is not None else {}
         sys.exit(
-            launch_main_application(
+            launch_main_gui(
                 no_splash=bool(ctx_obj.get("no_splash", False)),
                 ide_gui=bool(ctx_obj.get("ide_gui", False)),
             )
@@ -233,7 +231,7 @@ def main_app():
     )
     def unload_engines_cmd():
         """Unload all registered engines."""
-        result = unload_all()
+        result = unload_all_engines()
         if result["status"] == "success":
             info(f"{result['message']}")
             if result["unloaded"]:

cli/dedicated.py

@@ -6,12 +6,12 @@
 import shlex
 from pathlib import Path
 
-from EngineLoader import available_engines, unload_all
-
-from .launchers import (
-    launch_bcasl_standalone,
-    launch_engines_only_standalone,
-    launch_main_application,
+from .lazy_ops import (
+    available_engine_ids,
+    launch_bcasl_gui,
+    launch_engines_gui,
+    launch_main_gui,
+    unload_all_engines,
 )
 from .output import error, info, plain, success, warn
 from .system_info import print_system_info
@@ -222,7 +222,7 @@ def _resolve_workspace(raw: str | None) -> str | None:
 
 def _run_engines(args: list[str]) -> int:
     if "--dry-run" in args or "-d" in args:
-        engines = available_engines()
+        engines = available_engine_ids()
         if _RICH_CONSOLE is not None and Table is not None:
             table = Table(
                 title=f"Available engines ({len(engines)})", header_style="bold magenta"
@@ -238,12 +238,12 @@ def _run_engines(args: list[str]) -> int:
                 plain(f"  • {eid}")
         return 0
     workspace = _resolve_workspace(args[0]) if args else None
-    return launch_engines_only_standalone(workspace)
+    return launch_engines_gui(workspace)
 
 
 def _run_bcasl(args: list[str]) -> int:
     workspace = _resolve_workspace(args[0]) if args else None
-    return launch_bcasl_standalone(workspace)
+    return launch_bcasl_gui(workspace)
 
 
 def _new_bcasl_app(workspace: str | None = None):
@@ -591,7 +591,7 @@ def _run_engine_command(args: list[str]) -> int:
 
 
 def _run_unload() -> int:
-    result = unload_all()
+    result = unload_all_engines()
     if result["status"] == "success":
         success(result["message"])
         if result["unloaded"]:
@@ -720,7 +720,7 @@ def run_dedicated_cli(app_version: str) -> int:
                         plain("Usage: main [--ide-gui]")
                         ide_gui = False
                         break
-                launch_main_application(no_splash=False, ide_gui=ide_gui)
+                launch_main_gui(no_splash=False, ide_gui=ide_gui)
                 continue
             if cmd == "bcasl":
                 if args and args[0].lower() in ("help", "list", "run"):

cli/entrypoint.py

@@ -8,7 +8,7 @@
 
 from .click_app import build_cli, has_click
 from .fallback import run as run_fallback
-from .runtime import install_runtime, handle_fatal
+from .runtime import install_runtime, handle_fatal, should_enable_qt
 
 
 def _resolve_app_version() -> str:
@@ -27,12 +27,12 @@ def _resolve_app_version() -> str:
 
 def main(argv: list[str] | None = None) -> int:
     app_version = _resolve_app_version()
-    args = list(argv) if argv is not None else None
+    args = list(argv) if argv is not None else list(sys.argv[1:])
     if args and "--verbose" in args:
         import os
 
         os.environ["PYCOMPILER_VERBOSE"] = "1"
-    install_runtime(app_version)
+    install_runtime(app_version, enable_qt=should_enable_qt(args))
 
     if has_click():
         try:

cli/fallback.py

@@ -7,12 +7,12 @@
 from pathlib import Path
 from typing import Iterable, Optional
 
-from EngineLoader import unload_all
-
-from .launchers import (
-    launch_bcasl_standalone,
-    launch_engines_only_standalone,
-    launch_main_application,
+from .lazy_ops import (
+    available_engine_ids,
+    launch_bcasl_gui,
+    launch_engines_gui,
+    launch_main_gui,
+    unload_all_engines,
 )
 from .dedicated import run_dedicated_cli
 from .output import error, info, plain, warn
@@ -85,7 +85,7 @@ def run(argv: Optional[list[str]], app_version: str) -> int:
             print_system_info(app_version)
             return 0
         if args[0] == "--unload":
-            result = unload_all()
+            result = unload_all_engines()
             if result["status"] == "success":
                 info(f"{result['message']}")
                 if result["unloaded"]:
@@ -97,7 +97,7 @@ def run(argv: Optional[list[str]], app_version: str) -> int:
             return 0 if result["status"] == "success" else 1
         if args[0] == "bcasl":
             workspace_dir = args[1] if len(args) > 1 else None
-            return launch_bcasl_standalone(workspace_dir)
+            return launch_bcasl_gui(workspace_dir)
         if args[0] == "engines":
             sub_args = args[1:]
             if (
@@ -106,18 +106,16 @@ def run(argv: Optional[list[str]], app_version: str) -> int:
                 or "--dry-run" in sub_args
                 or "-d" in sub_args
             ):
-                from EngineLoader import available_engines
-
-                engines = available_engines()
+                engines = available_engine_ids()
                 plain(f"Available engines ({len(engines)}):")
                 for eid in engines:
                     plain(f"  - {eid}")
                 return 0
 
             workspace_dir = _maybe_workspace(sub_args)
-            return launch_engines_only_standalone(workspace_dir)
+            return launch_engines_gui(workspace_dir)
         if args[0] == "unload":
-            result = unload_all()
+            result = unload_all_engines()
             if result["status"] == "success":
                 info(f"{result['message']}")
                 if result["unloaded"]:
@@ -132,6 +130,6 @@ def run(argv: Optional[list[str]], app_version: str) -> int:
         plain(USAGE)
         return 1
 
-    return launch_main_application(
+    return launch_main_gui(
         no_splash=no_splash, ide_gui=ide_gui, classic_gui=classic_gui
     )

cli/lazy_ops.py

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Ague Samuel Amen
+
+from __future__ import annotations
+
+
+def unload_all_engines():
+    from EngineLoader import unload_all
+
+    return unload_all()
+
+
+def available_engine_ids() -> list[str]:
+    from EngineLoader import available_engines
+
+    return list(available_engines())
+
+
+def launch_bcasl_gui(workspace_dir: str | None = None) -> int:
+    from .launchers import launch_bcasl_standalone
+
+    return launch_bcasl_standalone(workspace_dir)
+
+
+def launch_engines_gui(workspace_dir: str | None = None) -> int:
+    from .launchers import launch_engines_only_standalone
+
+    return launch_engines_only_standalone(workspace_dir)
+
+
+def launch_main_gui(
+    no_splash: bool = False, ide_gui: bool = False, classic_gui: bool = False
+) -> int:
+    from .launchers import launch_main_application
+
+    return launch_main_application(
+        no_splash=no_splash,
+        ide_gui=ide_gui,
+        classic_gui=classic_gui,
+    )

cli/runtime.py

@@ -215,11 +215,46 @@ def handle_fatal(exc_info) -> None:
     _excepthook(*exc_info)
 
 
-def install_runtime(app_version: str) -> None:
+def should_enable_qt(argv: list[str] | None) -> bool:
+    """Return True only when the requested command path really needs Qt startup."""
+    args = list(argv or [])
+    if not args:
+        return True
+
+    if any(flag in args for flag in ("--help", "-h", "--version", "-v", "--info", "--cli", "--help-all")):
+        return False
+
+    if "--classic-gui" in args or "--ide-gui" in args:
+        return True
+
+    if "--unload" in args:
+        return False
+
+    cmd = None
+    for token in args:
+        if not token.startswith("-"):
+            cmd = token
+            break
+
+    if cmd is None:
+        return True
+    if cmd in ("main",):
+        return True
+    if cmd in ("unload", "version", "help", "info", "engine"):
+        return False
+    if cmd == "engines":
+        return not any(flag in args for flag in ("--dry-run", "-d"))
+    if cmd == "bcasl":
+        return False
+    return False
+
+
+def install_runtime(app_version: str, enable_qt: bool = True) -> None:
     ensure_sys_path()
     configure_logging()
     configure_env()
     enable_faulthandler()
-    install_qt_metadata(app_version)
-    install_qt_handlers()
+    if enable_qt:
+        install_qt_metadata(app_version)
+        install_qt_handlers()
     install_signal_handlers()

tests/test_cli_headless_runtime.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Ague Samuel Amen
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from cli import click_app, dedicated, fallback
+from cli.runtime import should_enable_qt
+
+
+def test_should_enable_qt_for_headless_commands() -> None:
+    assert should_enable_qt(["--help"]) is False
+    assert should_enable_qt(["--version"]) is False
+    assert should_enable_qt(["--info"]) is False
+    assert should_enable_qt(["--cli"]) is False
+    assert should_enable_qt(["--unload"]) is False
+    assert should_enable_qt(["engines", "--dry-run"]) is False
+    assert should_enable_qt(["engine", "list"]) is False
+    assert should_enable_qt(["bcasl", "list"]) is False
+
+
+def test_should_enable_qt_for_gui_commands() -> None:
+    assert should_enable_qt([]) is True
+    assert should_enable_qt(["main"]) is True
+    assert should_enable_qt(["--ide-gui"]) is True
+    assert should_enable_qt(["engines"]) is True
+
+
+def test_cli_modules_import_without_qt_bootstrap_side_effects() -> None:
+    assert callable(click_app.build_cli)
+    assert callable(fallback.run)
+    assert callable(dedicated.run_dedicated_cli)