Unify project identification: use absolute directory path and only in CLI allow project name

Author: Aksem

docs/cli.md

@@ -52,7 +52,7 @@ python -m finecode run [options] <action> [<action> ...] [payload] [--config.<ke
 | Option | Description |
 |---|---|
 | `--workdir=<path>` | Use `<path>` as the workspace root instead of `cwd` |
-| `--project=<name>` | Run only in this project. Repeatable for multiple projects. |
+| `--project=<name>` | Run only in this project (matched by `[project].name` from `pyproject.toml`). Repeatable for multiple projects. |
 | `--concurrently` | Run actions concurrently within each project |
 | `--shared-server` | Connect to the shared persistent WM Server instead of starting a dedicated one |
 | `--log-level=<level>` | Set log level: `TRACE`, `DEBUG`, `INFO`, `WARNING`, `ERROR` (default: `INFO`) |
@@ -127,7 +127,7 @@ See [Preparing Environments](guides/preparing-environments.md) for a full explan
 |---|---|
 | `--recreate` | Delete and recreate all venvs from scratch |
 | `--env-names=<name>` | Restrict handler dependency installation to the named env(s). Repeatable. See note below. |
-| `--project=<name>` | Restrict preparation to the named project(s). Repeatable. |
+| `--project=<name>` | Restrict preparation to the named project(s) (matched by `[project].name` from `pyproject.toml`). Repeatable. |
 | `--log-level=<level>` | Set log level: `TRACE`, `DEBUG`, `INFO`, `WARNING`, `ERROR` (default: `INFO`) |
 | `--debug` | Wait for a debugpy client on port 5680 before starting |
 | `--dev-env=<env>` | Override the detected dev environment. One of: `ai`, `ci`, `cli`, `ide`, `precommit` (default: auto-detected) |
@@ -149,7 +149,7 @@ Output is written to `<cwd>/finecode_config_dump/`.
 
 | Option | Description |
 |---|---|
-| `--project=<name>` | **(Required)** Project to dump config for |
+| `--project=<name>` | **(Required)** Project to dump config for (matched by `[project].name` from `pyproject.toml`) |
 | `--log-level=<level>` | Set log level: `TRACE`, `DEBUG`, `INFO`, `WARNING`, `ERROR` (default: `INFO`) |
 | `--debug` | Wait for a debugpy client on port 5680 |
 | `--dev-env=<env>` | Override the detected dev environment. One of: `ai`, `ci`, `cli`, `ide`, `precommit` (default: auto-detected) |

docs/concepts.md

@@ -105,6 +105,12 @@ A **Source Artifact** is a unit of source code that build/publish-style actions
 
 When a source artifact includes FineCode configuration — a `pyproject.toml` with a `[tool.finecode]` section — the Workspace Manager discovers it automatically under the workspace roots provided by the client. Some CLI flags and protocol fields still use the word “project” for compatibility.
 
+### Soruce Artifact identification
+
+The canonical external identifier for a source artifact is its **absolute directory path** (e.g. `/home/user/myrepo/my_package`). This is always unique, language-agnostic, and is what `list_projects` returns in the `path` field. All WM API consumers (LSP, MCP, JSON-RPC) use paths.
+
+The human-readable **project name** is taken from the `[project].name` field in `pyproject.toml`. Names are unique within a workspace in practice (two packages with the same name would break dependency resolution), but paths are used in the API to eliminate any ambiguity. The CLI is the only interface that accepts names — it resolves them to paths before making API calls.
+
 A source artifact may belong to a **workspace** — a set of related source artifacts, often a single directory root but sometimes multiple directories. FineCode handles multi-artifact workspaces transparently: running `python -m finecode run lint` from the workspace root runs lint in all source artifacts that define it.
 
 ## Workspace Manager and Extension Runner

src/finecode/cli_app/commands/dump_config_cmd.py

@@ -31,23 +31,24 @@ async def dump_config(
         client = ApiClient()
         await client.connect("127.0.0.1", port)
         try:
-            result = await client.add_dir(workdir_path, projects=[project_name])
+            result = await client.add_dir(workdir_path)
             projects = result.get("projects", [])
             project = next(
                 (p for p in projects if p["name"] == project_name), None
             )
             if project is None:
                 raise DumpFailed(f"Project '{project_name}' not found")
 
-            project_dir_path = pathlib.Path(project["path"])
+            project_path = project["path"]
+            project_dir_path = pathlib.Path(project_path)
             source_file_path = project_dir_path / "pyproject.toml"
             target_file_path = project_dir_path / "finecode_config_dump" / "pyproject.toml"
 
             try:
-                project_raw_config = await client.get_project_raw_config(project_name)
+                project_raw_config = await client.get_project_raw_config(project_path)
                 await client.run_action(
                     action="dump_config",
-                    project=project_name,
+                    project=project_path,
                     params={
                         "source_file_path": str(source_file_path),
                         "project_raw_config": project_raw_config,

src/finecode/cli_app/commands/prepare_envs_cmd.py

@@ -106,13 +106,16 @@ async def _run(
         if p["path"] != workdir_str and p["status"] == "CONFIG_VALID"
     ]
 
+    project_paths: list[str] | None = None
     if project_names is not None:
         unknown = [
             n for n in project_names if not any(p["name"] == n for p in projects)
         ]
         if unknown:
             raise PrepareEnvsFailed(f"Unknown project(s): {unknown}")
         other_projects = [p for p in other_projects if p["name"] in project_names]
+        # Resolve names to paths for all subsequent API calls (canonical identifier)
+        project_paths = [p["path"] for p in projects if p["name"] in project_names]
 
     logger.info(f"Found {len(projects)} project(s): {[p['name'] for p in projects]}")
 
@@ -123,14 +126,14 @@ async def _check_or_remove_dw(project: dict) -> None:
         if recreate:
             logger.trace(f"Recreate env 'dev_workspace' in project '{project['name']}'")
             try:
-                await client.remove_env(project["name"], "dev_workspace")
+                await client.remove_env(project["path"], "dev_workspace")
             except ApiError as exc:
                 raise PrepareEnvsFailed(
                     f"Failed to remove env for '{project['name']}': {exc}"
                 ) from exc
         else:
             try:
-                valid = await client.check_env(project["name"], "dev_workspace")
+                valid = await client.check_env(project["path"], "dev_workspace")
             except ApiError as exc:
                 raise PrepareEnvsFailed(
                     f"Failed to check env for '{project['name']}': {exc}"
@@ -141,7 +144,7 @@ async def _check_or_remove_dw(project: dict) -> None:
                     f"invalid, recreating it"
                 )
                 try:
-                    await client.remove_env(project["name"], "dev_workspace")
+                    await client.remove_env(project["path"], "dev_workspace")
                 except ApiError as exc:
                     raise PrepareEnvsFailed(
                         f"Failed to remove invalid env for '{project['name']}': {exc}"
@@ -174,7 +177,7 @@ async def _check_or_remove_dw(project: dict) -> None:
     try:
         create_dw_result = await client.run_action(
             action="create_envs",
-            project=current_project["name"],
+            project=current_project["path"],
             # 'recreate' is handled for dev_workspace envs above, no need to pass here
             params={"envs": dw_envs},
             options=dw_options,
@@ -192,7 +195,7 @@ async def _check_or_remove_dw(project: dict) -> None:
     try:
         prepare_dw_result = await client.run_action(
             action="prepare_handler_envs",
-            project=current_project["name"],
+            project=current_project["path"],
             params={"envs": dw_envs},
             options=dw_options,
         )
@@ -228,7 +231,7 @@ async def _check_or_remove_dw(project: dict) -> None:
     try:
         create_result = await client.run_batch(
             actions=["create_envs"],
-            projects=project_names,
+            projects=project_paths,
             options=common_options,
         )
     except ApiError as exc:
@@ -239,7 +242,7 @@ async def _check_or_remove_dw(project: dict) -> None:
     try:
         runners_result = await client.run_batch(
             actions=["prepare_runner_envs"],
-            projects=project_names,
+            projects=project_paths,
             options=common_options,
         )
     except ApiError as exc:
@@ -251,7 +254,7 @@ async def _check_or_remove_dw(project: dict) -> None:
     try:
         batch_result = await client.run_batch(
             actions=["prepare_handler_envs"],
-            projects=project_names,
+            projects=project_paths,
             params=handler_params,
             options=common_options,
         )

src/finecode/cli_app/commands/run_cmd.py

@@ -56,10 +56,21 @@ async def run_actions(
                         "Warning: --config overrides are ignored in --shared-server mode. ",
                         err=True,
                     )
-            await client.add_dir(
-                workdir_path,
-                projects=projects_names if own_server else None,
-            )
+            await client.add_dir(workdir_path)
+
+            # Resolve project names (CLI option) to paths (canonical API identifier).
+            project_paths: list[str] | None = None
+            if projects_names is not None:
+                all_projects = await client.list_projects()
+                unknown = [
+                    n for n in projects_names
+                    if not any(p["name"] == n for p in all_projects)
+                ]
+                if unknown:
+                    raise RunFailed(f"Unknown project(s): {unknown}")
+                project_paths = [
+                    p["path"] for p in all_projects if p["name"] in projects_names
+                ]
 
             params_by_project: dict[str, dict[str, typing.Any]] = {}
             if map_payload_fields:
@@ -73,7 +84,7 @@ async def run_actions(
             try:
                 batch_result = await client.run_batch(
                     actions=actions,
-                    projects=projects_names,
+                    projects=project_paths,
                     params=action_payload,
                     params_by_project=params_by_project or None,
                     options={

src/finecode/mcp_server.py

@@ -33,7 +33,7 @@ def _register_action_tools(mcp: FastMCP, actions: list[dict]) -> None:
 
         def _make_handler(action_name: str):
             async def handler(
-                project: str,
+                project: str,  # absolute path to the project directory (e.g. /home/user/myrepo)
                 file_paths: list[str] | None = None,
             ) -> dict:
                 return await _wm_client.run_action(

src/finecode/wm_server/config/read_configs.py

@@ -54,7 +54,7 @@ async def read_projects_in_dir(
         is_new_project = def_file.parent not in ws_context.ws_projects
         if is_new_project:
             new_project = domain.Project(
-                name=def_file.parent.name,
+                name=project_def.get("project", {}).get("name", def_file.parent.name),
                 dir_path=def_file.parent,
                 def_path=def_file,
                 status=status,

src/finecode/wm_server/wm_server.py

@@ -145,6 +145,13 @@ def _project_to_dict(project: domain.Project) -> dict:
     }
 
 
+def _find_project_by_path(
+    ws_context: context.WorkspaceContext, project_path: str
+) -> domain.Project | None:
+    """Look up a project by its absolute directory path (canonical external identifier)."""
+    return ws_context.ws_projects.get(pathlib.Path(project_path))
+
+
 # -- Implemented handlers --------------------------------------------------
 
 
@@ -158,22 +165,22 @@ async def _handle_list_projects(
 async def _handle_get_project_raw_config(
     params: dict | None, ws_context: context.WorkspaceContext
 ) -> dict:
-    """Return the resolved raw config for a project by name.
+    """Return the resolved raw config for a project by path.
 
-    Params: ``{"project": "project_name"}``
+    Params: ``{"project": "/abs/path/to/project"}``
     Result: ``{"rawConfig": {...}}``
     """
     params = params or {}
-    project_name = params.get("project")
-    if not project_name:
+    project_path = params.get("project")
+    if not project_path:
         raise ValueError("project parameter is required")
 
-    for project_dir_path, project in ws_context.ws_projects.items():
-        if project.name == project_name:
-            raw_config = ws_context.ws_projects_raw_configs.get(project_dir_path, {})
-            return {"rawConfig": raw_config}
+    project = _find_project_by_path(ws_context, project_path)
+    if project is None:
+        raise ValueError(f"Project '{project_path}' not found")
 
-    raise ValueError(f"Project '{project_name}' not found")
+    raw_config = ws_context.ws_projects_raw_configs.get(project.dir_path, {})
+    return {"rawConfig": raw_config}
 
 
 async def _handle_find_project_for_file(
@@ -223,7 +230,7 @@ async def _handle_add_dir(
         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).
-      projects: list[str] | null - optional list of project names to initialize.
+      projects: list[str] | null - optional list of project paths (absolute) to initialize.
         Projects not in this list are discovered but not config-initialized or
         started. Omit (or pass null) to initialize all projects.
         Calling add_dir again for the same dir with a different filter (or no
@@ -257,7 +264,7 @@ async def _handle_add_dir(
     ]
 
     if projects_filter is not None:
-        projects_to_init = [p for p in projects_to_init if p.name in projects_filter]
+        projects_to_init = [p for p in projects_to_init if str(p.dir_path) in projects_filter]
 
     for project in projects_to_init:
         await read_configs.read_project_config(
@@ -350,19 +357,19 @@ async def _handle_remove_dir(
 async def _handle_list_actions(
     params: dict | None, ws_context: context.WorkspaceContext
 ) -> dict:
-    """List available actions, optionally filtered by project name."""
+    """List available actions, optionally filtered by project path."""
     project_filter = (params or {}).get("project")
     actions = []
     for project in ws_context.ws_projects.values():
-        if project_filter and project.name != project_filter:
+        if project_filter and str(project.dir_path) != project_filter:
             continue
         if not isinstance(project, domain.CollectedProject):
             continue
         for action in project.actions:
             actions.append({
                 "name": action.name,
                 "source": action.source,
-                "project": project.name,
+                "project": str(project.dir_path),
                 "handlers": [
                     {"name": h.name, "source": h.source, "env": h.env}
                     for h in action.handlers
@@ -386,12 +393,8 @@ async def _handle_run_action(
     if not project_name:
         raise ValueError("project parameter is required")
 
-    # Find the project
-    project = None
-    for proj in ws_context.ws_projects.values():
-        if proj.name == project_name:
-            project = proj
-            break
+    # Find the project by its absolute directory path (canonical external identifier)
+    project = _find_project_by_path(ws_context, project_name)
 
     if project is None:
         raise ValueError(f"Project '{project_name}' not found")
@@ -533,7 +536,7 @@ async def _handle_start_runners(
 
     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]
+        projects = [p for p in projects if str(p.dir_path) in project_names]
 
     try:
         await runner_manager.start_runners_with_presets(
@@ -551,7 +554,7 @@ async def _handle_runners_check_env(
 ) -> dict:
     """Check whether an environment is valid for a given project.
 
-    Params: ``{"project": "project_name", "envName": "dev_workspace"}``
+    Params: ``{"project": "/abs/path/to/project", "envName": "dev_workspace"}``
     Result: ``{"valid": bool}``
     """
     from finecode.wm_server.runner import runner_manager
@@ -563,9 +566,7 @@ async def _handle_runners_check_env(
     if not project_name or not env_name:
         raise ValueError("project and envName are required")
 
-    project = next(
-        (p for p in ws_context.ws_projects.values() if p.name == project_name), None
-    )
+    project = _find_project_by_path(ws_context, project_name)
     if project is None:
         raise ValueError(f"Project '{project_name}' not found")
 
@@ -582,7 +583,7 @@ async def _handle_runners_remove_env(
 
     Stops the runner if running, then deletes the environment directory.
 
-    Params: ``{"project": "project_name", "envName": "dev_workspace"}``
+    Params: ``{"project": "/abs/path/to/project", "envName": "dev_workspace"}``
     Result: ``{}``
     """
     from finecode.wm_server.runner import runner_manager
@@ -594,9 +595,7 @@ async def _handle_runners_remove_env(
     if not project_name or not env_name:
         raise ValueError("project and envName are required")
 
-    project = next(
-        (p for p in ws_context.ws_projects.values() if p.name == project_name), None
-    )
+    project = _find_project_by_path(ws_context, project_name)
     if project is None:
         raise ValueError(f"Project '{project_name}' not found")
 
@@ -747,7 +746,7 @@ async def _handle_run_batch(
 
     Params:
       actions: list[str] - action names to run
-      projects: list[str] | None - project names to filter; absent/null means all projects
+      projects: list[str] | None - project paths (absolute) to filter; absent/null means all projects
       params: dict - action payload shared across all projects
       params_by_project: dict[str, dict] - per-project payload overrides keyed by project path string
       options:
@@ -786,13 +785,10 @@ async def _handle_run_batch(
     # Build actions_by_project (path -> [action_names])
     if project_names is not None:
         actions_by_project: dict[pathlib.Path, list[str]] = {}
-        for project_name in project_names:
-            project = next(
-                (p for p in ws_context.ws_projects.values() if p.name == project_name),
-                None,
-            )
+        for project_path_str in project_names:
+            project = _find_project_by_path(ws_context, project_path_str)
             if project is None:
-                raise ValueError(f"Project '{project_name}' not found")
+                raise ValueError(f"Project '{project_path_str}' not found")
             actions_by_project[project.dir_path] = list(actions)
     else:
         actions_by_project = run_service.find_projects_with_actions(ws_context, actions)