Migrate prepare_envs to external API server

Author: Aksem

docs/api-protocol.md

@@ -97,7 +97,7 @@ The server internally calls
 #### `workspace/addDir`
 
 Add a workspace directory. Discovers projects, reads configs, collects actions,
-and starts extension runners.
+and optionally starts extension runners.
 
 > **Design note:** Ideally, workspace directories would be a single shared
 > definition independent of which client connects (LSP, MCP, CLI). Currently,
@@ -108,15 +108,20 @@ and starts extension runners.
 > of directories is not environment-specific.
 
 - **Type:** request
-- **Clients:** LSP
+- **Clients:** LSP, CLI
 - **Status:** implemented
 
 **Params:**
 
 ```json
-{"dir_path": "/path/to/workspace"}
+{"dir_path": "/path/to/workspace", "start_runners": true}
 ```
 
+`start_runners` is optional (default: `true`). When `false`, the server reads
+configs and collects actions without starting any extension runners. Use this
+when runner environments may not exist yet (e.g. before running `prepare-envs`).
+Actions are still available in the result so clients can validate the workspace.
+
 **Result:**
 
 ```json
@@ -127,6 +132,31 @@ and starts extension runners.
 }
 ```
 
+`status` values: `"CONFIG_VALID"`, `"CONFIG_INVALID"`
+
+---
+
+#### `workspace/startRunners`
+
+Start extension runners for all (or specified) projects. Only starts runners
+that are not already running — complements existing runner state rather than
+replacing it. Also resolves preset-defined actions so that `actions/run` can
+find them.
+
+- **Type:** request
+- **Clients:** CLI
+- **Status:** implemented
+
+**Params:**
+
+```json
+{"projects": ["my_project"]}
+```
+
+`projects` is optional. If omitted, starts runners for all projects.
+
+**Result:** `{}`
+
 ---
 
 #### `workspace/setConfigOverrides`
@@ -569,6 +599,48 @@ Restart an extension runner. Optionally start in debug mode.
 
 ---
 
+#### `runners/checkEnv`
+
+Check whether the named environment for a project is valid (i.e. the virtualenv
+exists and its dependencies are correctly installed).
+
+- **Type:** request
+- **Clients:** CLI
+- **Status:** implemented
+
+**Params:**
+
+```json
+{"project": "my_project", "env_name": "dev_workspace"}
+```
+
+**Result:**
+
+```json
+{"valid": true}
+```
+
+---
+
+#### `runners/removeEnv`
+
+Remove the named environment for a project. If a runner is currently using that
+environment, it is stopped first.
+
+- **Type:** request
+- **Clients:** CLI
+- **Status:** implemented
+
+**Params:**
+
+```json
+{"project": "my_project", "env_name": "dev_workspace"}
+```
+
+**Result:** `{}`
+
+---
+
 ### `server/` — Server Lifecycle & Notifications
 
 #### `server/shutdown`

src/finecode/api_client.py

@@ -236,9 +236,45 @@ async def run_action(
             body["params"] = params
         return await self.request("actions/run", body)
 
-    async def add_dir(self, dir_path: pathlib.Path) -> dict:
-        """Add a workspace directory. Returns {projects: [...]}."""
-        return await self.request("workspace/addDir", {"dir_path": str(dir_path)})
+    async def add_dir(self, dir_path: pathlib.Path, start_runners: bool = True) -> dict:
+        """Add a workspace directory. Returns {projects: [...]}.
+
+        When ``start_runners=False`` the server reads configs and collects
+        actions without starting any extension runners.  Use this when runner
+        environments may not exist yet (e.g. before ``prepare-envs``).
+        """
+        return await self.request(
+            "workspace/addDir",
+            {"dir_path": str(dir_path), "start_runners": start_runners},
+        )
+
+    async def start_runners(self, projects: list[str] | None = None) -> None:
+        """Start extension runners for all (or specified) projects.
+
+        Complements any already-running runners — only missing runners are
+        started.  Also resolves presets so ``project.actions`` is up to date.
+        """
+        params: dict = {}
+        if projects is not None:
+            params["projects"] = projects
+        await self.request("workspace/startRunners", params)
+
+    async def check_env(self, project: str, env_name: str) -> bool:
+        """Return whether the named environment is valid for a project."""
+        result = await self.request(
+            "runners/checkEnv", {"project": project, "env_name": env_name}
+        )
+        if not isinstance(result, dict) or "valid" not in result:
+            raise ApiResponseError(
+                "runners/checkEnv", f"missing 'valid' field, got {result!r}"
+            )
+        return result["valid"]
+
+    async def remove_env(self, project: str, env_name: str) -> None:
+        """Remove the named environment for a project."""
+        await self.request(
+            "runners/removeEnv", {"project": project, "env_name": env_name}
+        )
 
     async def remove_dir(self, dir_path: pathlib.Path) -> None:
         """Remove a workspace directory."""

src/finecode/api_server/api_server.py

@@ -241,12 +241,22 @@ async def _handle_find_project_for_file(
 async def _handle_add_dir(
     params: dict | None, ws_context: context.WorkspaceContext
 ) -> dict:
-    """Add a workspace directory. Discovers projects, reads configs, starts runners."""
-    from finecode.api_server.config import read_configs
+    """Add a workspace directory. Discovers projects, reads configs, starts runners.
+
+    Params:
+      dir_path: str - absolute path to the workspace directory
+      start_runners: bool - whether to start extension runners (default true).
+        When false, configs are read and actions collected without starting any
+        runners. Useful when runner environments may not exist yet (e.g. before
+        running prepare-envs).
+    """
+    from finecode.api_server.config import collect_actions, read_configs
     from finecode.api_server.runner import runner_manager
     from finecode.api_server.runner.runner_client import RunnerStatus
 
+    params = params or {}
     dir_path = pathlib.Path(params["dir_path"])
+    start_runners: bool = params.get("start_runners", True)
     logger.trace(f"Add ws dir: {dir_path}")
 
     if dir_path in ws_context.ws_dirs_paths:
@@ -260,6 +270,21 @@ async def _handle_add_dir(
             project=project, ws_context=ws_context, resolve_presets=False
         )
 
+    if not start_runners:
+        # Collect actions directly from raw config without needing runners.
+        from finecode.api_server.config import config_models
+        for project in new_projects:
+            if project.status == domain.ProjectStatus.CONFIG_VALID:
+                try:
+                    collect_actions.collect_actions(
+                        project_path=project.dir_path, ws_context=ws_context
+                    )
+                except config_models.ConfigurationError as exc:
+                    logger.warning(
+                        f"Failed to collect actions for {project.name}: {exc.message}"
+                    )
+        return {"projects": [_project_to_dict(p) for p in new_projects]}
+
     try:
         await runner_manager.start_runners_with_presets(
             projects=new_projects,
@@ -492,6 +517,101 @@ async def _handle_runners_restart(
     return {}
 
 
+async def _handle_start_runners(
+    params: dict | None, ws_context: context.WorkspaceContext
+) -> dict:
+    """Start extension runners for all (or specified) projects.
+
+    Complements any runners already running — only missing runners are started.
+    Resolves presets so that ``project.actions`` reflects preset-defined handlers.
+
+    Params: ``{"projects": ["project_name", ...]}`` (optional, default: all projects)
+    Result: ``{}``
+    """
+    from finecode.api_server.runner import runner_manager
+
+    params = params or {}
+    project_names: list[str] | None = params.get("projects")
+
+    projects = list(ws_context.ws_projects.values())
+    if project_names is not None:
+        projects = [p for p in projects if p.name in project_names]
+
+    try:
+        await runner_manager.start_runners_with_presets(
+            projects=projects,
+            ws_context=ws_context,
+        )
+    except runner_manager.RunnerFailedToStart as exc:
+        raise ValueError(f"Starting runners failed: {exc.message}") from exc
+
+    return {}
+
+
+async def _handle_runners_check_env(
+    params: dict | None, ws_context: context.WorkspaceContext
+) -> dict:
+    """Check whether an environment is valid for a given project.
+
+    Params: ``{"project": "project_name", "env_name": "dev_workspace"}``
+    Result: ``{"valid": bool}``
+    """
+    from finecode.api_server.runner import runner_manager
+
+    params = params or {}
+    project_name = params.get("project")
+    env_name = params.get("env_name")
+
+    if not project_name or not env_name:
+        raise ValueError("project and env_name are required")
+
+    project = next(
+        (p for p in ws_context.ws_projects.values() if p.name == project_name), None
+    )
+    if project is None:
+        raise ValueError(f"Project '{project_name}' not found")
+
+    valid = await runner_manager.check_runner(
+        runner_dir=project.dir_path, env_name=env_name
+    )
+    return {"valid": valid}
+
+
+async def _handle_runners_remove_env(
+    params: dict | None, ws_context: context.WorkspaceContext
+) -> dict:
+    """Remove an environment for a given project.
+
+    Stops the runner if running, then deletes the environment directory.
+
+    Params: ``{"project": "project_name", "env_name": "dev_workspace"}``
+    Result: ``{}``
+    """
+    from finecode.api_server.runner import runner_manager
+
+    params = params or {}
+    project_name = params.get("project")
+    env_name = params.get("env_name")
+
+    if not project_name or not env_name:
+        raise ValueError("project and env_name are required")
+
+    project = next(
+        (p for p in ws_context.ws_projects.values() if p.name == project_name), None
+    )
+    if project is None:
+        raise ValueError(f"Project '{project_name}' not found")
+
+    # Stop the runner if it is currently running.
+    runners = ws_context.ws_projects_extension_runners.get(project.dir_path, {})
+    runner = runners.get(env_name)
+    if runner is not None:
+        await runner_manager.stop_extension_runner(runner=runner)
+
+    runner_manager.remove_runner_venv(runner_dir=project.dir_path, env_name=env_name)
+    return {}
+
+
 async def _handle_server_reset(
     params: dict | None, ws_context: context.WorkspaceContext
 ) -> dict:
@@ -814,6 +934,7 @@ async def _handle_run_with_partial_results_task(
     "workspace/removeDir": _handle_remove_dir,
     "workspace/setConfigOverrides": _handle_set_config_overrides,
     "workspace/getProjectRawConfig": _handle_get_project_raw_config,
+    "workspace/startRunners": _handle_start_runners,
     # actions/
     "actions/list": _handle_list_actions,
     "actions/getTree": _handle_get_tree,
@@ -824,6 +945,8 @@ async def _handle_run_with_partial_results_task(
     # runners:
     "runners/list": _handle_runners_list,
     "runners/restart": _handle_runners_restart,
+    "runners/checkEnv": _handle_runners_check_env,
+    "runners/removeEnv": _handle_runners_remove_env,
     # server/
     "server/reset": _handle_server_reset,
     "server/shutdown": _stub("server/shutdown"),

src/finecode/cli.py

@@ -387,7 +387,8 @@ def run(ctx) -> None:
 @click.option("--trace", "trace", is_flag=True, default=False)
 @click.option("--debug", "debug", is_flag=True, default=False)
 @click.option("--recreate", "recreate", is_flag=True, default=False)
-def prepare_envs(trace: bool, debug: bool, recreate: bool) -> None:
+@click.option("--shared-server", "shared_server", is_flag=True, default=False)
+def prepare_envs(trace: bool, debug: bool, recreate: bool, shared_server: bool) -> None:
     """
     `prepare-envs` should be called from workspace/project root directory.
     """
@@ -407,11 +408,13 @@ def prepare_envs(trace: bool, debug: bool, recreate: bool) -> None:
     try:
         asyncio.run(
             prepare_envs_cmd.prepare_envs(
-                workdir_path=pathlib.Path(os.getcwd()), recreate=recreate
+                workdir_path=pathlib.Path(os.getcwd()),
+                recreate=recreate,
+                own_server=not shared_server,
             )
         )
     except prepare_envs_cmd.PrepareEnvsFailed as exception:
-        click.echo(exception.args[0], err=True)
+        click.echo(exception.message, err=True)
         sys.exit(1)
     except Exception as exception:
         logger.exception(exception)