Mettre a jour la documentation des engines et de la CLI

Author: raidos23

README.md

@@ -19,7 +19,7 @@ Build Python apps with a predictable workflow, a configurable pre-compile pipeli
 - **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.
-- **Zero-Config auto-mapping for 80+ libraries**: automatic import detection via requirements covers major AI, modern web, data science, and automation stacks, with engine-specific arguments applied without manual tuning.
+- **Core auto-mapping for 80+ libraries**: automatic import detection from requirements and imports covers major AI, modern web, data science, and automation stacks, with engine-specific arguments applied through the engine mapping layer.
 - **Simplified build inclusions**: `build.include` forces package bundling and ARK translates it automatically per engine.
 - **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.
@@ -54,45 +54,56 @@ The PyCompiler ARK CLI provides a structured set of commands for workspace manag
 
 ```bash
 # Workspace Initialization
-python3 -m pycompiler_ark init --entry src/main.py [--icon icon.ico] [--with-venv]
+pycompiler_ark init --entry <path> [--icon <path>] [--with-venv] [--install-requirements] [--generate-requirements] [--apply-internal] [-y|--yes]
 
 # Building
-python3 -m pycompiler_ark build                      # Build using ark.yml engine
-python3 -m pycompiler_ark build --engine nuitka      # Override engine
-python3 -m pycompiler_ark build --lock latest         # Rebuild from the latest lock file
+pycompiler_ark build [-y|--yes] [-v|--verbose] [--json]
+pycompiler_ark build --engine <id> [-y|--yes]
+pycompiler_ark build --lock [file] [-y|--yes]
 
 # Execution
-python3 -m pycompiler_ark run bcasl                  # Execute BCASL pipeline
-python3 -m pycompiler_ark run bcasl --list-plugins   # List active plugins
+pycompiler_ark run bcasl [-y|--yes] [--list-plugins]
 
 # GUI
-python3 -m pycompiler_ark gui                        # Launch modern IDE-like GUI
-python3 -m pycompiler_ark gui --legacy               # Launch classic GUI
+pycompiler_ark gui
+pycompiler_ark gui --legacy
 ```
 
 ### Developer Commands
 
 ```bash
 # Discovery
-python3 -m pycompiler_ark list engines               # List available engines
-python3 -m pycompiler_ark list plugins               # List available BCASL plugins
+pycompiler_ark list engines
+pycompiler_ark list plugins
+
+# Configuration
+pycompiler_ark set user-engine-dir <path>
+pycompiler_ark set user-plugin-dir <path>
+pycompiler_ark set dev-engine-dir <path>
+pycompiler_ark set dev-plugin-dir <path>
+
+pycompiler_ark get user-engine-dir
+pycompiler_ark get user-plugin-dir
+pycompiler_ark get dev-engine-dir
+pycompiler_ark get dev-plugin-dir
 
-# Configuration (User Paths)
-python3 -m pycompiler_ark set user-engine-dir /path  # Set custom engine directory
-python3 -m pycompiler_ark get user-engine-dir        # Retrieve path
+pycompiler_ark unset user-engine-dir
+pycompiler_ark unset user-plugin-dir
+pycompiler_ark unset dev-engine-dir
+pycompiler_ark unset dev-plugin-dir
 
 # Scaffolding
-python3 -m pycompiler_ark scaffold engine demo       # Create a new engine template
-python3 -m pycompiler_ark scaffold plugin-bcasl demo # Create a new BCASL plugin template
+pycompiler_ark scaffold engine <name> [--path <dir>]
+pycompiler_ark scaffold plugin-bcasl <name> [--path <dir>]
 ```
 
 ### JSON Output
 
 For CI/CD and scripting, key commands support the `--json` flag to return machine-readable results:
 
 ```bash
-python3 -m pycompiler_ark build --json
-python3 -m pycompiler_ark init --entry main.py --json
+pycompiler_ark build --json
+pycompiler_ark init --entry main.py --json
 ```
 
 ---

docs/how_to_create_an_engine.md

@@ -17,7 +17,7 @@ A PyCompiler ARK engine is a Python package placed in `pycompiler_ark/engines/<e
 
 - `pycompiler_ark/engines/<engine_id>/__init__.py`: engine code, registration, UI.
 - `pycompiler_ark/engines/<engine_id>/languages/<code>.json`: optional translations.
-- `pycompiler_ark/engines/<engine_id>/mapping.json`: optional mapping for the auto-builder.
+- `pycompiler_ark/engines/<engine_id>/mapping.json`: optional mapping used by the core auto-mapping system.
 - Optional internal modules, assets, helpers.
 
 #### **Minimal Example**
@@ -323,26 +323,15 @@ Notes.
 - `load_engine_language_file(engine_package, lang)` is still available if you need custom/manual loading.
 - If a key is missing, always provide a safe fallback string.
 
-**Auto Command Builder (Integrated)**
-The auto-builder is integrated into the core compilation pipeline. It can read
-`mapping.json` from the engine package, the workspace `engines/<engine_id>/`
-folder, or the `PYCOMPILER_MAPPING` environment variable to generate options
-from detected modules.
+**Core Auto-Mapping**
+PyCompiler ARK handles auto-mapping in the core pipeline. Engine authors do
+not need to implement a separate auto-mapping layer in their engine code.
 
-PyCompiler ARK expands this layer into a zero-config auto-mapping system that
-applies engine-specific flags automatically when imports are detected, so
-engine authors only need to fill the gaps not covered by the core mapping
-catalog.
+For engines that need import-to-flag mapping, provide a `mapping.json` file in
+the engine package. The core reads it and merges the generated flags into the
+final command.
 
-You no longer need to call `compute_auto_for_engine` manually in your `build_command`. The core runner will:
-
-1. Prefer `requirements.txt` or `requirements.in` when present.
-2. Fall back to `pyproject.toml` dependencies.
-3. Fall back to scanning Python imports.
-4. Read the engine mapping and generate the appropriate flags.
-5. Insert them into your command, usually before the entry point.
-
-#### **Minimal mapping.json example.**
+#### **Minimal `mapping.json` example**
 
 ```json
 {
@@ -360,12 +349,12 @@ You no longer need to call `compute_auto_for_engine` manually in your `build_com
 Key points.
 
 - Top-level keys are package names.
-- Engine values accept `str`, `list[str]`, or `dict` with `args` or `flags`.
+- Engine values can be strings, lists of flags, or structured objects accepted
+  by the core mapping parser.
 - `"{import_name}"` is replaced by the matched import name.
 - Use `build.include` when a package must be bundled even if the core mapping
   or import scanner does not trigger it automatically.
-- For advanced logic, expose `AUTO_BUILDER`, `get_auto_builder()`, or
-  `register_auto_builder()` in `pycompiler_ark/engines/<engine_id>/auto_plugins.py` or the workspace `engines/<engine_id>/auto_plugins.py`.
+- Engine authors only need to maintain `mapping.json` for this layer.
 
 **Deep Examples Catalog (40)**
 Each example includes context, intent, and a working pattern. Adjust IDs and labels to match your engine.