Simplify prepare-envs by reducing prepare_runner_envs and prepare_handler_envs to single install_envs action. Improve docs how does it work

Author: Aksem

docs/cli.md

@@ -133,7 +133,7 @@ See [Preparing Environments](guides/preparing-environments.md) for a full explan
 | `--dev-env=<env>` | Override the detected dev environment. One of: `ai`, `ci`, `cli`, `ide`, `precommit` (default: auto-detected) |
 
 
-!!! note `--env-names` restricts only the final `prepare_handler_envs` step. The `create_envs` and `prepare_runner_envs` steps still run for **all** envs regardless of this flag — envs and runners must exist for every env even when you only need to update dependencies in one of them.
+!!! note `--env-names` restricts only the `install_envs` step. The `create_envs` step still runs for **all** envs regardless of this flag — virtualenvs must exist for every env even when you only need to update dependencies in one of them.
 
 ---
 

docs/guides/preparing-environments.md

@@ -2,12 +2,12 @@
 
 FineCode runs handlers in purpose-specific virtual environments. Handlers that share the same `env` name (e.g. `dev_no_runtime`) run in the same virtualenv. Before handlers can execute, their environments must exist and contain the right dependencies. This guide explains how that process works and how to control it.
 
-## The three-step sequence
+## The two-step sequence
 
-Environment preparation is split into three distinct actions that must run in order:
+Environment preparation is split into two distinct actions that must run in order:
 
 ```
-create_envs  →  prepare_runner_envs  →  prepare_handler_envs
+create_envs  →  install_envs
 ```
 
 ### Step 1 — `create_envs`
@@ -25,33 +25,40 @@ runtime          = ["fastapi>=0.100", ...]
 
 → Creates `.venvs/dev_workspace/`, `.venvs/dev_no_runtime/`, `.venvs/runtime/`.
 
-### Step 2 — `prepare_runner_envs`
+### Step 2 — `install_envs`
 
-Installs the **Extension Runner** (`finecode_extension_runner`) into each virtualenv. This is what lets FineCode start runners that can actually load handler code.
+Installs the full dependency set into each virtualenv. This reads the `dependency-groups` entries and calls `install_deps_in_env` for each env, including `finecode_extension_runner` and all handler tool dependencies (e.g. ruff, mypy).
 
-Preset packages are only installed in `dev_workspace` (handled during the bootstrap phase — see below). Only the runner is installed into other envs here — not the full handler dependency trees.
+After this step every handler has all its dependencies available and can execute.
 
-!!! note
-    `prepare_runner_envs` must run **after** `create_envs` and **before** runners are started. Runners are started automatically between steps 2 and 3 by the WM during `prepare-envs`.
+---
 
-### Step 3 — `prepare_handler_envs`
+## The `dev_workspace` bootstrap
 
-Installs the full dependency set for each handler into its declared `env` virtualenv. This reads the `dependency-groups` entries and calls `install_deps_in_env` for each env.
+The `dev_workspace` env is special: it contains FineCode itself and the preset packages. The handlers that implement `create_envs` and `install_envs` live inside `dev_workspace` — which creates a bootstrapping constraint.
 
-After this step every handler has all its dependencies available and can execute.
+### Workspace root bootstrap (manual, one-time)
 
----
+The workspace root's `dev_workspace` is the **seed** for everything. `prepare-envs` cannot run unless FineCode is already installed somewhere, so the workspace root's `dev_workspace` must be created manually on a fresh checkout:
+
+```bash
+python -m venv .venvs/dev_workspace
+source .venvs/dev_workspace/bin/activate   # Windows: .venvs\dev_workspace\Scripts\activate
+python -m pip install --group="dev_workspace"
+```
+
+This is the only step that cannot be automated by FineCode itself. See [Getting Started](../getting-started.md) for the full first-time setup sequence.
 
-## The `dev_workspace` bootstrap env
+### Subproject bootstrap (automated by `prepare-envs`)
 
-The `dev_workspace` env is special: it contains FineCode itself and the preset packages. This means the handlers that implement `prepare_runner_envs` and `prepare_handler_envs` *live inside* `dev_workspace`.
+For subprojects in the workspace, `prepare-envs` creates their `dev_workspace` envs automatically — **before** starting any runners — using the workspace root's handler configuration:
 
-Because of this, `prepare-envs` handles `dev_workspace` separately, **before** starting runners:
+1. `create_envs` (subproject `dev_workspace` envs) — create the venvs
+2. `install_envs` (subproject `dev_workspace` envs) — install FineCode + presets
 
-1. `create_envs` (dev_workspace only) — create the venv if it doesn't exist
-2. `prepare_handler_envs` (dev_workspace only) — install FineCode + presets
+**Requirement:** the workspace root's `create_envs` and `install_envs` configuration must produce a valid `dev_workspace` for every subproject. In practice this is rarely a constraint: `dev_workspace` envs exist only to run FineCode and preset packages, so their setup is uniform across projects. If a subproject genuinely requires different handler configuration for either action, its `dev_workspace` must be bootstrapped manually the same way as the workspace root's.
 
-Only after this bootstrap are runners started, and only then can the remaining steps run across all envs.
+Only after all `dev_workspace` envs exist are runners started, and only then can the remaining steps run across all envs.
 
 ---
 
@@ -66,11 +73,10 @@ python -m finecode prepare-envs
 This is the only command most users need. It:
 
 1. Discovers all projects in the workspace
-2. Bootstraps `dev_workspace` (steps 1–2 above) for each project
+2. Bootstraps `dev_workspace` for each subproject (`create_envs` + `install_envs`, using workspace root config)
 3. Starts Extension Runners
 4. Runs `create_envs` across all projects
-5. Runs `prepare_runner_envs` across all projects
-6. Runs `prepare_handler_envs` across all projects
+5. Runs `install_envs` across all projects
 
 See [CLI reference — prepare-envs](../cli.md#prepare-envs) for available options.
 
@@ -96,22 +102,21 @@ Only prepares environments for the listed projects. Useful in a large workspaces
 python -m finecode prepare-envs --env-names=dev_no_runtime
 ```
 
-Restricts the `prepare_handler_envs` step (step 3) to the named environments. The `create_envs` and `prepare_runner_envs` steps still run for **all** envs regardless of this flag.
+Restricts the `install_envs` step (step 2) to the named environments. The `create_envs` step still runs for **all** envs regardless of this flag.
 
-**Why?** Virtualenvs and runners must exist for every env — they are cheap to create and skip if already valid. Filtering at those steps would leave envs in a broken state if they don't exist yet.
+**Why?** Virtualenvs must exist for every env — they are cheap to create and skip if already valid. Filtering at that step would leave envs in a broken state if they don't exist yet.
 
 Useful when you've added a new handler in one env and want to update only that env without reinstalling everything.
 
 ---
 
 ## Calling actions directly
 
-The three actions (`create_envs`, `prepare_runner_envs`, `prepare_handler_envs`) are standard FineCode actions and can be invoked individually via the WM API or `python -m finecode run`. This is useful when writing custom orchestration.
+The two actions (`create_envs`, `install_envs`) are standard FineCode actions and can be invoked individually via the WM API or `python -m finecode run`. This is useful when writing custom orchestration.
 
 | Action | Source |
 |---|---|
 | `create_envs` | `finecode_extension_api.actions.create_envs.CreateEnvsAction` |
-| `prepare_runner_envs` | `finecode_extension_api.actions.prepare_runner_envs.PrepareRunnerEnvsAction` |
-| `prepare_handler_envs` | `finecode_extension_api.actions.prepare_handler_envs.PrepareHandlerEnvsAction` |
+| `install_envs` | `finecode_extension_api.actions.install_envs.InstallEnvsAction` |
 
 See [Built-in Actions reference](../reference/actions.md) for payload fields and result types.

…lers/prepare_handler_env_install_deps.py …tin_handlers/install_env_install_deps.pyfinecode_builtin_handlers/src/finecode_builtin_handlers/prepare_handler_env_install_deps.py renamed to finecode_builtin_handlers/src/finecode_builtin_handlers/install_env_install_deps.py finecode_builtin_handlers/src/finecode_builtin_handlers/prepare_handler_env_install_deps.py renamed to finecode_builtin_handlers/src/finecode_builtin_handlers/install_env_install_deps.py

@@ -3,23 +3,23 @@
 from finecode_extension_api import code_action
 from finecode_extension_api.actions import (
     install_deps_in_env as install_deps_in_env_action,
-    prepare_handler_env as prepare_handler_env_action,
+    install_env as install_env_action,
 )
-from finecode_extension_api.actions.prepare_handler_envs import (
-    PrepareHandlerEnvsRunResult,
+from finecode_extension_api.actions.install_envs import (
+    InstallEnvsRunResult,
 )
 from finecode_extension_api.interfaces import iactionrunner, ilogger
 from finecode_builtin_handlers.dependency_config_utils import process_raw_deps
 
 
 @dataclasses.dataclass
-class PrepareHandlerEnvInstallDepsHandlerConfig(code_action.ActionHandlerConfig): ...
+class InstallEnvInstallDepsHandlerConfig(code_action.ActionHandlerConfig): ...
 
 
-class PrepareHandlerEnvInstallDepsHandler(
+class InstallEnvInstallDepsHandler(
     code_action.ActionHandler[
-        prepare_handler_env_action.PrepareHandlerEnvAction,
-        PrepareHandlerEnvInstallDepsHandlerConfig,
+        install_env_action.InstallEnvAction,
+        InstallEnvInstallDepsHandlerConfig,
     ]
 ):
     def __init__(
@@ -30,14 +30,14 @@ def __init__(
 
     async def run(
         self,
-        payload: prepare_handler_env_action.PrepareHandlerEnvRunPayload,
-        run_context: prepare_handler_env_action.PrepareHandlerEnvRunContext,
-    ) -> PrepareHandlerEnvsRunResult:
+        payload: install_env_action.InstallEnvRunPayload,
+        run_context: install_env_action.InstallEnvRunContext,
+    ) -> InstallEnvsRunResult:
         env = payload.env
         project_def = run_context.project_def
         if project_def is None:
             raise code_action.ActionFailedException(
-                "project_def must be set by PrepareHandlerEnvReadConfigHandler"
+                "project_def must be set by InstallEnvReadConfigHandler"
             )
 
         install_deps_in_env_action_instance = self.action_runner.get_action_by_name(
@@ -82,4 +82,4 @@ async def run(
             payload=install_deps_payload,
             meta=run_context.meta,
         )
-        return PrepareHandlerEnvsRunResult(errors=result.errors)
+        return InstallEnvsRunResult(errors=result.errors)

…dlers/prepare_handler_env_read_config.py …ltin_handlers/install_env_read_config.pyfinecode_builtin_handlers/src/finecode_builtin_handlers/prepare_handler_env_read_config.py renamed to finecode_builtin_handlers/src/finecode_builtin_handlers/install_env_read_config.py finecode_builtin_handlers/src/finecode_builtin_handlers/prepare_handler_env_read_config.py renamed to finecode_builtin_handlers/src/finecode_builtin_handlers/install_env_read_config.py

@@ -2,23 +2,23 @@
 
 from finecode_extension_api import code_action
 from finecode_extension_api.actions import (
-    prepare_handler_env as prepare_handler_env_action,
+    install_env as install_env_action,
 )
-from finecode_extension_api.actions.prepare_handler_envs import (
-    PrepareHandlerEnvsRunResult,
+from finecode_extension_api.actions.install_envs import (
+    InstallEnvsRunResult,
 )
 from finecode_extension_api.interfaces import ilogger, iprojectinfoprovider
 from finecode_builtin_handlers import dependency_config_utils
 
 
 @dataclasses.dataclass
-class PrepareHandlerEnvReadConfigHandlerConfig(code_action.ActionHandlerConfig): ...
+class InstallEnvReadConfigHandlerConfig(code_action.ActionHandlerConfig): ...
 
 
-class PrepareHandlerEnvReadConfigHandler(
+class InstallEnvReadConfigHandler(
     code_action.ActionHandler[
-        prepare_handler_env_action.PrepareHandlerEnvAction,
-        PrepareHandlerEnvReadConfigHandlerConfig,
+        install_env_action.InstallEnvAction,
+        InstallEnvReadConfigHandlerConfig,
     ]
 ):
     def __init__(
@@ -31,14 +31,14 @@ def __init__(
 
     async def run(
         self,
-        payload: prepare_handler_env_action.PrepareHandlerEnvRunPayload,
-        run_context: prepare_handler_env_action.PrepareHandlerEnvRunContext,
-    ) -> PrepareHandlerEnvsRunResult:
+        payload: install_env_action.InstallEnvRunPayload,
+        run_context: install_env_action.InstallEnvRunContext,
+    ) -> InstallEnvsRunResult:
         project_raw_config = await self.project_info_provider.get_project_raw_config(
             payload.env.project_def_path
         )
         dependency_config_utils.make_project_config_pip_compatible(
             project_raw_config, payload.env.project_def_path
         )
         run_context.project_def = project_raw_config
-        return PrepareHandlerEnvsRunResult(errors=[])
+        return InstallEnvsRunResult(errors=[])

…rs/prepare_handler_envs_discover_envs.py …n_handlers/install_envs_discover_envs.pyfinecode_builtin_handlers/src/finecode_builtin_handlers/prepare_handler_envs_discover_envs.py renamed to finecode_builtin_handlers/src/finecode_builtin_handlers/install_envs_discover_envs.py finecode_builtin_handlers/src/finecode_builtin_handlers/prepare_handler_envs_discover_envs.py renamed to finecode_builtin_handlers/src/finecode_builtin_handlers/install_envs_discover_envs.py

@@ -2,7 +2,7 @@
 
 from finecode_extension_api import code_action
 from finecode_extension_api.actions import (
-    prepare_handler_envs as prepare_handler_envs_action,
+    install_envs as install_envs_action,
 )
 from finecode_extension_api.actions.create_envs import EnvInfo
 from finecode_extension_api.interfaces import (
@@ -13,13 +13,13 @@
 
 
 @dataclasses.dataclass
-class PrepareHandlerEnvsDiscoverEnvsHandlerConfig(code_action.ActionHandlerConfig): ...
+class InstallEnvsDiscoverEnvsHandlerConfig(code_action.ActionHandlerConfig): ...
 
 
-class PrepareHandlerEnvsDiscoverEnvsHandler(
+class InstallEnvsDiscoverEnvsHandler(
     code_action.ActionHandler[
-        prepare_handler_envs_action.PrepareHandlerEnvsAction,
-        PrepareHandlerEnvsDiscoverEnvsHandlerConfig,
+        install_envs_action.InstallEnvsAction,
+        InstallEnvsDiscoverEnvsHandlerConfig,
     ]
 ):
     """Discover and populate run_context.envs from the current project's config.
@@ -42,9 +42,9 @@ def __init__(
 
     async def run(
         self,
-        payload: prepare_handler_envs_action.PrepareHandlerEnvsRunPayload,
-        run_context: prepare_handler_envs_action.PrepareHandlerEnvsRunContext,
-    ) -> prepare_handler_envs_action.PrepareHandlerEnvsRunResult:
+        payload: install_envs_action.InstallEnvsRunPayload,
+        run_context: install_envs_action.InstallEnvsRunContext,
+    ) -> install_envs_action.InstallEnvsRunResult:
         if payload.envs:
             envs = list(payload.envs)
         else:
@@ -64,10 +64,10 @@ async def run(
                 )
                 for env_name in deps_groups
             ]
-            
+
             if payload.env_names is not None:
                 envs = [e for e in envs if e.name in payload.env_names]
 
         self.logger.debug(f"Discovered handler envs: {[e.name for e in envs]}")
         run_context.envs = envs
-        return prepare_handler_envs_action.PrepareHandlerEnvsRunResult(errors=[])
+        return install_envs_action.InstallEnvsRunResult(errors=[])

…andlers/prepare_handler_envs_dispatch.py …uiltin_handlers/install_envs_dispatch.pyfinecode_builtin_handlers/src/finecode_builtin_handlers/prepare_handler_envs_dispatch.py renamed to finecode_builtin_handlers/src/finecode_builtin_handlers/install_envs_dispatch.py finecode_builtin_handlers/src/finecode_builtin_handlers/prepare_handler_envs_dispatch.py renamed to finecode_builtin_handlers/src/finecode_builtin_handlers/install_envs_dispatch.py

@@ -3,23 +3,23 @@
 
 from finecode_extension_api import code_action
 from finecode_extension_api.actions import (
-    prepare_handler_env as prepare_handler_env_action,
-    prepare_handler_envs as prepare_handler_envs_action,
+    install_env as install_env_action,
+    install_envs as install_envs_action,
 )
 from finecode_extension_api.interfaces import iactionrunner, ilogger
 
 
 @dataclasses.dataclass
-class PrepareHandlerEnvsDispatchHandlerConfig(code_action.ActionHandlerConfig): ...
+class InstallEnvsDispatchHandlerConfig(code_action.ActionHandlerConfig): ...
 
 
-class PrepareHandlerEnvsDispatchHandler(
+class InstallEnvsDispatchHandler(
     code_action.ActionHandler[
-        prepare_handler_envs_action.PrepareHandlerEnvsAction,
-        PrepareHandlerEnvsDispatchHandlerConfig,
+        install_envs_action.InstallEnvsAction,
+        InstallEnvsDispatchHandlerConfig,
     ]
 ):
-    """Dispatch a prepare_handler_env call per environment concurrently."""
+    """Dispatch an install_env call per environment concurrently."""
 
     def __init__(
         self, action_runner: iactionrunner.IActionRunner, logger: ilogger.ILogger
@@ -29,28 +29,28 @@ def __init__(
 
     async def run(
         self,
-        payload: prepare_handler_envs_action.PrepareHandlerEnvsRunPayload,
-        run_context: prepare_handler_envs_action.PrepareHandlerEnvsRunContext,
-    ) -> prepare_handler_envs_action.PrepareHandlerEnvsRunResult:
-        prepare_handler_env_action_instance = self.action_runner.get_action_by_name(
-            name="prepare_handler_env",
-            expected_type=prepare_handler_env_action.PrepareHandlerEnvAction,
+        payload: install_envs_action.InstallEnvsRunPayload,
+        run_context: install_envs_action.InstallEnvsRunContext,
+    ) -> install_envs_action.InstallEnvsRunResult:
+        install_env_action_instance = self.action_runner.get_action_by_name(
+            name="install_env",
+            expected_type=install_env_action.InstallEnvAction,
         )
 
         if run_context.envs is None:
             raise code_action.ActionFailedException(
                 "envs must be populated must be provided in payload or populated by previous handlers"
             )
         tasks: list[
-            asyncio.Task[prepare_handler_envs_action.PrepareHandlerEnvsRunResult]
+            asyncio.Task[install_envs_action.InstallEnvsRunResult]
         ] = []
         try:
             async with asyncio.TaskGroup() as tg:
                 for env in run_context.envs:
                     task = tg.create_task(
                         self.action_runner.run_action(
-                            action=prepare_handler_env_action_instance,
-                            payload=prepare_handler_env_action.PrepareHandlerEnvRunPayload(
+                            action=install_env_action_instance,
+                            payload=install_env_action.InstallEnvRunPayload(
                                 env=env,
                             ),
                             meta=run_context.meta,
@@ -64,4 +64,4 @@ async def run(
         errors: list[str] = []
         for task in tasks:
             errors += task.result().errors
-        return prepare_handler_envs_action.PrepareHandlerEnvsRunResult(errors=errors)
+        return install_envs_action.InstallEnvsRunResult(errors=errors)