Bootstrap command. Fix 'create env' and 'install deps in env' handlers after migration to resource uri

Author: Aksem

.github/workflows/ci-cd.yml

@@ -55,15 +55,8 @@ jobs:
 
       - name: Install dependencies
         run: |
-          python -m venv .venvs/dev_workspace
+          pipx run finecode bootstrap
           source .venvs/dev_workspace/bin/activate
-          python -m pip install --upgrade pip==25.3
-
-          # split installation into 2 steps: first internal preset because it is not
-          # published as pypi package, so pip will fail to resolve it in dev_workspace
-          # group and only then other dependencies
-          python -m pip install -e ./finecode_dev_common_preset
-          python -m pip install --group="dev_workspace" -e . -e ./finecode_extension_runner
 
           python -m finecode prepare-envs
         shell: bash

docs/getting-started.md

@@ -4,11 +4,16 @@ This guide walks you through installing FineCode, applying an existing preset, a
 
 ## Prerequisites
 
-- Python 3.11–3.14
-- pip 25.1 or newer (for `--group` support)
+- Python 3.11–3.14 **or** [uv](https://docs.astral.sh/uv/) (which can install Python for you)
+
+No Python yet? Install `uv` (a single binary, no Python needed):
 
 ```bash
-python -m pip install --upgrade pip
+# Linux / macOS
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 
 ## 1. Add FineCode to your project
@@ -22,7 +27,19 @@ Add the `dev_workspace` dependency group to your `pyproject.toml`:
 dev_workspace = ["finecode==0.3.*"]
 ```
 
-Create the venv and install:
+Bootstrap the `dev_workspace` environment:
+
+```bash
+# Recommended — works with pipx (bundled with Python 3.13+) or uv:
+pipx run finecode bootstrap
+# or
+uvx finecode bootstrap
+```
+
+This creates `.venvs/dev_workspace/` with FineCode installed, using the exact
+versions specified in your `pyproject.toml`.
+
+**Manual alternative** (if you prefer not to use pipx/uvx — requires pip 25.1+):
 
 ```bash
 python -m venv .venvs/dev_workspace

docs/guides/preparing-environments.md

@@ -37,17 +37,37 @@ After this step every handler has all its dependencies available and can execute
 
 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.
 
-### Workspace root bootstrap (manual, one-time)
+### Workspace root bootstrap (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:
+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 before `prepare-envs` can run.
+
+Use the `bootstrap` command — it handles this automatically using the invoking Python (e.g. the pipx/uvx ephemeral environment):
+
+```bash
+# With pipx (bundled with Python 3.13+):
+pipx run finecode bootstrap
+
+# With uv (also works when you have no Python — uv installs it):
+uvx finecode bootstrap
+```
+
+> **Note:** `bootstrap` uses the built-in default handlers: `virtualenv` for environment creation and `pip` for dependency installation. If your project requires custom handlers for either action (e.g. a different package manager or venv backend), `bootstrap` is not suitable — you must bootstrap the `dev_workspace` manually (see the **Manual alternative** below) or via your own tooling.
+
+To delete and recreate an existing `dev_workspace`:
+
+```bash
+pipx run finecode bootstrap --recreate
+```
+
+**Manual alternative** (requires pip 25.1+):
 
 ```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.
+See [Getting Started](../getting-started.md) for the full first-time setup sequence.
 
 ### Subproject bootstrap (automated by `prepare-envs`)
 

extensions/fine_python_pip/src/fine_python_pip/install_deps_in_env_handler.py

@@ -4,6 +4,7 @@
 from finecode_extension_api import code_action
 from finecode_extension_api.actions.environments import install_deps_in_env_action
 from finecode_extension_api.interfaces import icommandrunner, ilogger
+from finecode_extension_api.resource_uri import resource_uri_to_path
 
 
 @dataclasses.dataclass
@@ -35,8 +36,8 @@ async def run(
     ) -> install_deps_in_env_action.InstallDepsInEnvRunResult:
         env_name = payload.env_name
         dependencies = payload.dependencies
-        venv_dir_path = payload.venv_dir_path
-        project_dir_path = payload.project_dir_path
+        venv_dir_path = resource_uri_to_path(payload.venv_dir_path)
+        project_dir_path = resource_uri_to_path(payload.project_dir_path)
         python_executable = venv_dir_path / "bin" / "python"
 
         cmd = self._construct_pip_install_cmd(

extensions/fine_python_virtualenv/src/fine_python_virtualenv/create_env_handler.py

@@ -6,6 +6,7 @@
 from finecode_extension_api.actions.environments import create_env_action
 from finecode_extension_api.actions.environments.create_envs_action import CreateEnvsRunResult
 from finecode_extension_api.interfaces import ifilemanager, ilogger
+from finecode_extension_api.resource_uri import resource_uri_to_path
 
 
 @dataclasses.dataclass
@@ -33,23 +34,29 @@ async def run(
         run_context: create_env_action.CreateEnvRunContext,
     ) -> CreateEnvsRunResult:
         env_info = payload.env
-        if payload.recreate and env_info.venv_dir_path.exists():
-            self.logger.debug(f"Remove virtualenv dir {env_info.venv_dir_path}")
-            await self.file_manager.remove_dir(env_info.venv_dir_path)
+        venv_dir_path = resource_uri_to_path(env_info.venv_dir_path)
+        if payload.recreate and venv_dir_path.exists():
+            self.logger.debug(f"Remove virtualenv dir {venv_dir_path}")
+            await self.file_manager.remove_dir(venv_dir_path)
 
-        self.logger.info(f"Creating virtualenv {env_info.venv_dir_path}")
-        if not env_info.venv_dir_path.exists():
+        self.logger.info(f"Creating virtualenv {venv_dir_path}")
+        # Check for pyvenv.cfg rather than the directory itself — the runner
+        # may have already created a logs/ subdirectory inside this path before
+        # the venv is set up, which would cause a directory-existence check to
+        # incorrectly skip venv creation.
+        venv_valid = (venv_dir_path / "pyvenv.cfg").exists()
+        if not venv_valid:
             try:
                 virtualenv.cli_run(
-                    [env_info.venv_dir_path.as_posix()],
+                    [venv_dir_path.as_posix()],
                     options=None,
                     setup_logging=False,
                     env=None,
                 )
             except Exception as exc:
                 return CreateEnvsRunResult(
                     errors=[
-                        f"Failed to create virtualenv {env_info.venv_dir_path}: {exc}"
+                        f"Failed to create virtualenv {venv_dir_path}: {exc}"
                     ]
                 )
         else:

pyproject.toml

@@ -24,6 +24,9 @@ dependencies = [
     "apischema==0.19.*",
 ]
 
+[project.scripts]
+finecode = "finecode.cli:cli"
+
 [dependency-groups]
 dev_workspace = [
     "build==1.2.2.post1",

src/finecode/cli.py

@@ -461,6 +461,43 @@ def prepare_envs(log_level: str, debug: bool, recreate: bool, shared_server: boo
         sys.exit(2)
 
 
+@cli.command()
+@click.option("--recreate", is_flag=True, default=False,
+              help="Delete and recreate dev_workspace if it already exists.")
+@click.option("--log-level", "log_level", default="INFO",
+              type=click.Choice(["TRACE", "DEBUG", "INFO", "WARNING", "ERROR"],
+              case_sensitive=False), show_default=True)
+def bootstrap(recreate: bool, log_level: str) -> None:
+    """Create the dev_workspace environment for the workspace root.
+
+    Intended as a one-time setup step before running prepare-envs.
+    Can be run via ``pipx run finecode bootstrap`` or ``uvx finecode bootstrap``
+    without a pre-existing virtualenv.
+    """
+    import asyncio
+
+    from finecode.cli_app.commands import bootstrap_cmd
+
+    logger_utils.init_logger(log_name="cli", log_level=log_level, stdout=True)
+    user_messages._notification_sender = show_user_message
+
+    try:
+        asyncio.run(
+            bootstrap_cmd.bootstrap(
+                workdir_path=pathlib.Path(os.getcwd()),
+                recreate=recreate,
+                log_level=log_level,
+            )
+        )
+    except bootstrap_cmd.BootstrapFailed as exception:
+        click.echo(exception.message, err=True)
+        sys.exit(1)
+    except Exception as exception:
+        logger.exception(exception)
+        click.echo("Unexpected error, see logs in file for more details", err=True)
+        sys.exit(2)
+
+
 @cli.command()
 @click.option("--log-level", "log_level", default="INFO", type=click.Choice(["TRACE", "DEBUG", "INFO", "WARNING", "ERROR"], case_sensitive=False), show_default=True)
 @click.option("--debug", "debug", is_flag=True, default=False)

src/finecode/cli_app/commands/_env_setup.py

@@ -0,0 +1,57 @@
+"""Shared helper for create_envs + install_envs used by bootstrap and prepare-envs."""
+from finecode.wm_client import ApiClient, ApiError
+
+
+class EnvSetupFailed(Exception):
+    def __init__(self, message: str) -> None:
+        self.message = message
+
+
+async def create_and_install_envs(
+    client: ApiClient,
+    project_path: str,
+    envs: list[dict],
+    dev_env: str = "cli",
+) -> None:
+    """Run ``create_envs`` then ``install_envs`` for the given environments.
+
+    Raises :class:`EnvSetupFailed` on any failure so callers can re-raise
+    with their own exception type.
+    """
+    options = {
+        "resultFormats": ["string"],
+        "trigger": "user",
+        "devEnv": dev_env,
+    }
+
+    try:
+        create_result = await client.run_action(
+            action="create_envs",
+            project=project_path,
+            params={"envs": envs},
+            options=options,
+        )
+    except ApiError as exc:
+        raise EnvSetupFailed(f"'create_envs' failed: {exc}") from exc
+    if create_result.get("returnCode", 0) != 0:
+        output = (create_result.get("resultByFormat") or {}).get("string", "")
+        raise EnvSetupFailed(
+            f"'create_envs' failed with return code "
+            f"{create_result['returnCode']}: {output}"
+        )
+
+    try:
+        install_result = await client.run_action(
+            action="install_envs",
+            project=project_path,
+            params={"envs": envs},
+            options=options,
+        )
+    except ApiError as exc:
+        raise EnvSetupFailed(f"'install_envs' failed: {exc}") from exc
+    if install_result.get("returnCode", 0) != 0:
+        output = (install_result.get("resultByFormat") or {}).get("string", "")
+        raise EnvSetupFailed(
+            f"'install_envs' failed with return code "
+            f"{install_result['returnCode']}: {output}"
+        )

src/finecode/cli_app/commands/bootstrap_cmd.py

@@ -0,0 +1,121 @@
+# docs: docs/cli.md
+import pathlib
+import sys
+
+from finecode.wm_client import ApiClient, ApiError  # ApiError used for start_runners check
+from finecode.wm_server import wm_lifecycle
+from finecode.cli_app.commands._env_setup import create_and_install_envs, EnvSetupFailed
+from loguru import logger
+
+
+class BootstrapFailed(Exception):
+    def __init__(self, message: str) -> None:
+        self.message = message
+
+
+async def bootstrap(
+    workdir_path: pathlib.Path,
+    recreate: bool = False,
+    log_level: str = "INFO",
+) -> None:
+    """Create the dev_workspace environment for the workspace root.
+
+    Uses the current Python process (sys.executable) as a temporary runner so
+    that ``create_envs`` and ``install_envs`` can run before the venv exists.
+    After bootstrap, run ``finecode prepare-envs`` to set up all other envs.
+    """
+    port_file = None
+    try:
+        port_file = wm_lifecycle.start_own_server(workdir_path, log_level=log_level)
+        try:
+            port = await wm_lifecycle.wait_until_ready_from_file(port_file)
+        except TimeoutError as exc:
+            raise BootstrapFailed(str(exc)) from exc
+
+        client = ApiClient()
+        await client.connect("127.0.0.1", port)
+        try:
+            await _run(client, workdir_path, recreate)
+        finally:
+            await client.close()
+    finally:
+        if port_file is not None and port_file.exists():
+            port_file.unlink(missing_ok=True)
+
+
+async def _run(
+    client: ApiClient,
+    workdir_path: pathlib.Path,
+    recreate: bool,
+) -> None:
+    venv_dir = workdir_path / ".venvs" / "dev_workspace"
+    workdir_str = str(workdir_path)
+
+    if venv_dir.exists() and not recreate:
+        logger.info(
+            f"dev_workspace already exists at '{venv_dir}'. "
+            "Use --recreate to delete and recreate it."
+        )
+        return
+
+    # Discover projects (no runners — venv may not exist yet).
+    logger.info("Discovering projects...")
+    result = await client.add_dir(workdir_path, start_runners=False)
+    projects: list[dict] = result.get("projects", [])
+
+    current_project = next((p for p in projects if p["path"] == workdir_str), None)
+    if current_project is None:
+        raise BootstrapFailed(
+            "bootstrap must be run from the workspace/project root"
+        )
+    if current_project["status"] == "CONFIG_INVALID":
+        raise BootstrapFailed(
+            f"Project '{current_project['name']}' has invalid configuration"
+        )
+
+    if venv_dir.exists():
+        # recreate=True (already handled False above)
+        logger.info(f"Removing existing dev_workspace at '{venv_dir}'...")
+        try:
+            await client.remove_env(workdir_str, "dev_workspace")
+        except ApiError as exc:
+            raise BootstrapFailed(
+                f"Failed to remove existing dev_workspace: {exc}"
+            ) from exc
+
+    # Start the dev_workspace runner using the current Python executable.
+    # This works even though the venv doesn't exist yet because sys.executable
+    # already has finecode and all handlers installed (e.g. via pipx/uvx).
+    logger.info(f"Starting temporary runner using {sys.executable}...")
+    try:
+        await client.start_runners(
+            projects=[workdir_str],
+            python_overrides={"dev_workspace": sys.executable},
+        )
+    except ApiError as exc:
+        raise BootstrapFailed(f"Failed to start runner: {exc}") from exc
+
+    dw_env = {
+        "name": "dev_workspace",
+        "venv_dir_path": venv_dir.as_uri(),
+        "project_def_path": (workdir_path / "pyproject.toml").as_uri(),
+    }
+
+    logger.info("Creating dev_workspace virtualenv and installing dependencies...")
+    try:
+        await create_and_install_envs(
+            client=client,
+            project_path=workdir_str,
+            envs=[dw_env],
+            dev_env="cli",
+        )
+    except EnvSetupFailed as exc:
+        raise BootstrapFailed(exc.message) from exc
+
+    logger.info(
+        f"Bootstrap complete. dev_workspace created at '{venv_dir}'.\n"
+        "Next step: run 'finecode prepare-envs' to set up all other environments."
+    )
+
+
+__all__ = ["bootstrap", "BootstrapFailed"]