docs: mise à jour complète de la documentation en anglais et synchronisation avec EngineRunner

Author: raidos23

README.md

@@ -15,15 +15,14 @@ Build Python apps with a predictable workflow, a configurable pre-compile pipeli
 ## Core capabilities
 
 - **BCASL pre-compile pipeline**: validation, preparation, transformation before the build, with timeouts and safety controls.
-- **Multi-engine builds**: switch between PyInstaller, Nuitka, and cx_Freeze without changing your workflow.
-- **Extensible engines**: create your own engine and add it to ARK++ when needed.
+- **Unified EngineRunner architecture**: a single source of truth for both CLI and GUI compilation, ensuring identical build results across all interfaces.
+- **BuildContext-driven builds**: engines receive a normalized project context, abstracting away the source of configuration (YAML vs. Lock files).
+- **Multi-engine support**: switch between PyInstaller, Nuitka, and cx_Freeze seamlessly.
+- **Extensible SDKs**: create new engines and BCASL plugins using simplified, consolidated APIs.
 - **Auto-detection for tricky dependencies**: engine-specific auto-args based on requirements or import scanning.
 - **Workspace-first UI**: filter files, manage exclusions, and follow progress and logs in one place.
 - **Venv-aware execution**: engines can use the project virtual environment automatically.
-- **Structured CLI**: 
-- **Extensible SDKs**: create new engines and BCASL plugins with the provided SDKs.
-- **Theme-aware dynamic colors and SVG icons**: 100% dynamic UI integration using QPalette and themed SVGs.
-- **Customizable**: theming and translations out of the box.
+- **Theme-aware dynamic UI**: 100% dynamic integration using QPalette and themed SVGs.
 
 ---
 
@@ -143,19 +142,15 @@ python pycompiler_ark.py init --entry main.py --json
 
 ## Project layout
 
-- `Ui/Cli/` — active ARK CLI entrypoints, runtime helpers, discovery, and command tree.
-- `Core/` — main UI logic.
-- `Core/IdeLikeGui/` — wiring layer for the IDE-like main GUI.
-- `ENGINES/` — built-in engines.
-- `EngineLoader/` — discovery and registry.
-- `Plugins/` — BCASL plugins.
-- `Plugins_SDK/` — plugin SDK.
-- `bcasl/` — BCASL core.
-- `Ui/Forms/` — Qt Designer UI forms.
-  - `Ui/Forms/classic_main_window.ui` — default main layout
-  - `Ui/Forms/ide_main_window.ui` — IDE-like layout
-- `languages/` — translations.
-- `themes/` — QSS themes.
+- `Ui/Cli/`: Command-line interface implementation and entry points.
+- `Core/`: Core business logic for compilation, workspace management, and settings.
+- `Core/Compiler/`: The **EngineRunner** and **MainProcess** (single source of truth for builds).
+- `engines/`: Built-in compilation engines (PyInstaller, Nuitka, cx_Freeze).
+- `bcasl/`: BCASL core engine and plugin loader.
+- `Plugins/`: Pre-compile pipeline plugins.
+- `engine_sdk/` & `Plugins_SDK/`: Developer kits for extending ARK.
+- `Ui/Forms/`: Qt Designer `.ui` files for the IDE-like and Classic layouts.
+- `languages/` & `themes/`: Application-wide translations and QSS themes.
 
 ---
 

docs/ark_main_config.md

@@ -1,16 +1,8 @@
 ## **ark.yml** — Workspace Configuration
 
-This file customizes how a workspace is scanned and built. It lives at the
-workspace root and is created automatically when the workspace is first set
-in the GUI (if missing).
+This file defines the project settings used to build the normalized **BuildContext**. It lives at the workspace root and is created automatically when the workspace is first set in the GUI (if missing).
 
-The configuration is loaded by `Core/Configs/` and merged with
-defaults.
-
-## Location
-
-The spec-first CLI requires `ark.yml` at the workspace root. The compatibility
-loader still accepts the older names used by the classic GUI path.
+The configuration is loaded by `Core/Configs/` and serves as the primary source of truth for project metadata.
 
 ## Minimal Example
 
@@ -29,61 +21,39 @@ workspace:
 build:
   engine: pyinstaller
   output: dist/
-  data: []
+  icon: assets/icon.ico
+  data:
+    - source: assets/
+      destination: assets/
 ```
 
 ## Build Entrypoint
 
-`project.entry` defines the single file to compile. It must be a path
-relative to the workspace root.
+`project.entry` defines the primary script to compile. It must be a path relative to the workspace root.
 
 Behavior:
-- If `entrypoint` is set and the file exists, only that file is compiled.
-- If it is missing or invalid, compilation is blocked until a valid entrypoint
-  is selected.
+- When a build is triggered (CLI or GUI), this entrypoint is used to populate the `BuildContext`.
+- In the GUI, you can select any file to compile, but the `project.entry` remains the default configuration.
+- If it is missing or invalid, compilation is blocked until a valid entrypoint is selected.
 
-GUI shortcut:
+GUI shortcuts:
 - Right‑click a file in the workspace list → **Set as entrypoint**.
 - Right‑click again → **Clear entrypoint**.
 - The entrypoint is marked with an icon in the list.
 
-## Notes
-
-- Keep paths relative (ex: `"src/main.py"`).
-- Entrypoint is stored in `ark.yml` as `project.entry` and can be edited manually.
-- This file is separate from `bcasl.yml` (which remains the canonical BCASL plugin config file).
-- A small compatibility bridge also exists under `plugins.*` for workspace-level BCASL defaults such as:
-  - `plugins.bcasl_enabled`
-  - `plugins.plugin_timeout`
-
-## Advanced Config Editor (GUI)
-
-The main GUI has a **Configurations avancées** button that opens a dedicated
-editor for:
-- `ark.yml`
-- `bcasl.yml`
-- `.ark/pref.json` (workspace‑specific preferences)
+## Relationship to BuildContext
 
-Features:
-- Monospace editor
-- Simple YAML/JSON syntax highlighting
-- Diff view before saving
-- Basic validation on save (YAML/JSON)
+The fields in `ark.yml` are mapped directly to the `BuildContext` data structure passed to engines:
 
-## Workspace Prefs (.ark/pref.json)
+| ark.yml field | BuildContext field |
+| :--- | :--- |
+| `project.name` | `project_name` |
+| `project.entry` | `entry_point` |
+| `workspace.exclude` | `exclude_patterns` |
+| `build.output` | `output_dir` |
+| `build.data` | `data_mappings` |
+| `build.icon` | `icon` |
 
-Per‑workspace preferences are stored in:
-```
-<workspace>/.ark/pref.json
-```
-
-Currently used keys:
-```json
-{
-  "venv_mode": "venv" | "system",
-  "venv_path": "/abs/path/to/venv" | null
-}
-```
+## Advanced Config Editor (GUI)
 
-These values are updated when you select a venv or System Python, and are
-re‑applied automatically when the workspace is loaded.
+The main GUI has a **Configurations avancées** button that opens a dedicated editor for `ark.yml`, `bcasl.yml`, and other configuration files.

docs/contributing.md

@@ -0,0 +1,30 @@
+# **Contributing to PyCompiler ARK**
+
+Thank you for your interest in contributing to ARK! This workshop is designed to be extensible through its multi-engine and pre-compile plugin systems.
+
+## **Where to Start?**
+
+If you are a developer looking to extend ARK's functionality, please refer to the following guides:
+
+- **Creating a Compilation Engine**: [docs/how_to_create_an_engine.md](how_to_create_an_engine.md)
+  Learn how to package and register a new compiler (e.g., Py2Exe, Docker).
+- **Creating a Pre-Compile Plugin**: [docs/how_to_create_a_bc_plugin.md](how_to_create_a_bc_plugin.md)
+  Learn how to add validation, cleanup, or preparation steps to the build pipeline.
+
+## **Technical Specifications**
+
+For a deeper dive into ARK's internal architecture, review our core specifications:
+
+- **BuildContext Spec**: [docs/dev_docs/ARK_BuildContext_v1.0.md](dev_docs/ARK_BuildContext_v1.0.md)
+- **CLI Spec**: [docs/dev_docs/ARK_Cli_v1.1.md](dev_docs/ARK_Cli_v1.1.md)
+- **Locking Spec**: [docs/dev_docs/ARK_Locking_v1.0.md](dev_docs/ARK_Locking_v1.0.md)
+
+## **Development Workflow**
+
+1.  **Code Style**: We use `ruff` for linting and `black` for formatting.
+2.  **Testing**: Run tests using `pytest`.
+3.  **Engine Registry**: New engines should be placed in the `ENGINES/` directory.
+
+## **License**
+
+By contributing, you agree that your contributions will be licensed under the project's **Apache-2.0** license.