python-delphi-lsp 2.3.1__tar.gz → 2.3.2__tar.gz

{python_delphi_lsp-2.3.1/python_delphi_lsp.egg-info → python_delphi_lsp-2.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-delphi-lsp
-Version: 2.3.1
+Version: 2.3.2
 Summary: Python Delphi/Object Pascal parser, semantic indexer, and language server.
 Author: Dark Light
 License-Expression: MPL-2.0
@@ -42,7 +42,7 @@ Dynamic: license-file
 
 `python-delphi-lsp` parses Delphi/Object Pascal, builds semantic and project
 indexes, serves LSP, and provides bounded codebase navigation for agents.
-Version 2.3.1 is authored by Dark Light and supports Windows, macOS, and Linux.
+Version 2.3.2 is authored by Dark Light and supports Windows, macOS, and Linux.
 
 ## Install and quick start
 
@@ -166,7 +166,8 @@ available without returning the complete file as agent context.
 Auto-discovery reads `.dpr`, `.dpk`, `.dproj`, `.cfg`, and `.dof` files.
 Its resolution order is:
 
-1. An explicit project selection takes precedence.
+1. An explicit `.dproj`, `.dpr`, or `.dpk` selection takes precedence. An
+   explicit `.dproj` resolves its `MainSource`.
 2. Otherwise, `.dpr` and `.dpk` candidates are considered.
 3. `MainSource` in a `.dproj` contributes its entry project.
 4. A selected entry associates same-stem `.dproj`, `.cfg`, and `.dof`.
@@ -175,11 +176,13 @@ Its resolution order is:
 6. Direct `Unit in 'path/Unit.pas'` references contribute their parent
    directory to unit search paths.
 
-A single discovered project is selected automatically. With no project entry,
-the server uses a synthetic workspace of supported sources. Scans skip build
-and cache directories such as `build`, `dist`, environments, VCS folders,
-`node_modules`, and tool caches. Missing paths and invalid metadata become
-problems; paths are not guessed.
+A single discovered project is selected automatically. With multiple project
+entries, a synthetic repository workspace containing every supported source is
+selected automatically while the concrete projects remain available. With no
+project entry, the same workspace model is used. Scans skip build and cache
+directories such as `build`, `dist`, environments, VCS folders, `node_modules`,
+and tool caches. Missing paths and invalid metadata become problems; paths are
+not guessed.
 
 ## Agent CLI and Interface/Protocol v2
 
@@ -197,7 +200,7 @@ delphi-lsp-agent view --root PATH [--project-file FILE] --layer LAYER
 delphi-lsp-agent index --root PATH [--project-file FILE] [--out FILE]
                        [--workers auto|N]
 delphi-lsp-agent query --root PATH ACTION [VALUE]
-                      [--project-id FILE] [--detail summary|declaration|members|context|body|implementations]
+                      [--project-id ID] [--detail summary|declaration|members|context|body|implementations]
                       [--relation references|callers|callees|uses|used_by|inherits|implements]
                       [--cursor TEXT] [--max-items INT] [--max-chars INT]
 delphi-lsp-agent skill install [--target PATH] [--force]
@@ -229,6 +232,32 @@ delphi-lsp-agent query --root PATH metrics UNIT_QUERY
 delphi-lsp-agent cache status --root PATH --format json
 ```
 
+The repository root is sufficient even when it contains many projects:
+
+```bash
+delphi-lsp-agent cache start --root PATH
+delphi-lsp-agent query --root PATH find TCustomer
+```
+
+This prewarms one bounded repository navigation index and requires no project
+selection. A `.dproj` is optional. Pass one when its project-specific compiler
+settings and `MainSource` should define the index:
+
+```bash
+delphi-lsp-agent cache start --root PATH --project-file relative/path/Main.dproj
+```
+
+An explicit `.dpr` or `.dpk` remains supported. To switch an already running
+repository cache to one of its concrete project views, list the projects and
+focus one by its returned `project_id`:
+
+```bash
+delphi-lsp-agent query --root PATH open
+delphi-lsp-agent query --root PATH focus --project-id PROJECT_ID
+```
+
+Selecting a project this way also prewarms its navigation cache.
+
 `inspect` uses the currently focused target, so call `focus TARGET_ID` before
 `inspect` unless a previous request already selected it.
 

{python_delphi_lsp-2.3.1 → python_delphi_lsp-2.3.2}/README.md

@@ -2,7 +2,7 @@
 
 `python-delphi-lsp` parses Delphi/Object Pascal, builds semantic and project
 indexes, serves LSP, and provides bounded codebase navigation for agents.
-Version 2.3.1 is authored by Dark Light and supports Windows, macOS, and Linux.
+Version 2.3.2 is authored by Dark Light and supports Windows, macOS, and Linux.
 
 ## Install and quick start
 
@@ -126,7 +126,8 @@ available without returning the complete file as agent context.
 Auto-discovery reads `.dpr`, `.dpk`, `.dproj`, `.cfg`, and `.dof` files.
 Its resolution order is:
 
-1. An explicit project selection takes precedence.
+1. An explicit `.dproj`, `.dpr`, or `.dpk` selection takes precedence. An
+   explicit `.dproj` resolves its `MainSource`.
 2. Otherwise, `.dpr` and `.dpk` candidates are considered.
 3. `MainSource` in a `.dproj` contributes its entry project.
 4. A selected entry associates same-stem `.dproj`, `.cfg`, and `.dof`.
@@ -135,11 +136,13 @@ Its resolution order is:
 6. Direct `Unit in 'path/Unit.pas'` references contribute their parent
    directory to unit search paths.
 
-A single discovered project is selected automatically. With no project entry,
-the server uses a synthetic workspace of supported sources. Scans skip build
-and cache directories such as `build`, `dist`, environments, VCS folders,
-`node_modules`, and tool caches. Missing paths and invalid metadata become
-problems; paths are not guessed.
+A single discovered project is selected automatically. With multiple project
+entries, a synthetic repository workspace containing every supported source is
+selected automatically while the concrete projects remain available. With no
+project entry, the same workspace model is used. Scans skip build and cache
+directories such as `build`, `dist`, environments, VCS folders, `node_modules`,
+and tool caches. Missing paths and invalid metadata become problems; paths are
+not guessed.
 
 ## Agent CLI and Interface/Protocol v2
 
@@ -157,7 +160,7 @@ delphi-lsp-agent view --root PATH [--project-file FILE] --layer LAYER
 delphi-lsp-agent index --root PATH [--project-file FILE] [--out FILE]
                        [--workers auto|N]
 delphi-lsp-agent query --root PATH ACTION [VALUE]
-                      [--project-id FILE] [--detail summary|declaration|members|context|body|implementations]
+                      [--project-id ID] [--detail summary|declaration|members|context|body|implementations]
                       [--relation references|callers|callees|uses|used_by|inherits|implements]
                       [--cursor TEXT] [--max-items INT] [--max-chars INT]
 delphi-lsp-agent skill install [--target PATH] [--force]
@@ -189,6 +192,32 @@ delphi-lsp-agent query --root PATH metrics UNIT_QUERY
 delphi-lsp-agent cache status --root PATH --format json
 ```
 
+The repository root is sufficient even when it contains many projects:
+
+```bash
+delphi-lsp-agent cache start --root PATH
+delphi-lsp-agent query --root PATH find TCustomer
+```
+
+This prewarms one bounded repository navigation index and requires no project
+selection. A `.dproj` is optional. Pass one when its project-specific compiler
+settings and `MainSource` should define the index:
+
+```bash
+delphi-lsp-agent cache start --root PATH --project-file relative/path/Main.dproj
+```
+
+An explicit `.dpr` or `.dpk` remains supported. To switch an already running
+repository cache to one of its concrete project views, list the projects and
+focus one by its returned `project_id`:
+
+```bash
+delphi-lsp-agent query --root PATH open
+delphi-lsp-agent query --root PATH focus --project-id PROJECT_ID
+```
+
+Selecting a project this way also prewarms its navigation cache.
+
 `inspect` uses the currently focused target, so call `focus TARGET_ID` before
 `inspect` unless a previous request already selected it.
 

python_delphi_lsp-2.3.2/delphi_lsp/_version.py

@@ -0,0 +1 @@
+__version__ = "2.3.2"

{python_delphi_lsp-2.3.1 → python_delphi_lsp-2.3.2}/delphi_lsp/agent_cache.py

@@ -639,6 +639,21 @@ def _read_startup_tail(diagnostics: object, *, max_bytes: int = _STARTUP_DIAGNOS
     return b""
 
 
+def _daemon_process_options() -> dict[str, object]:
+    options: dict[str, object] = {
+        "stdin": subprocess.DEVNULL,
+        "stdout": subprocess.DEVNULL,
+    }
+    if os.name == "nt":
+        options["creationflags"] = (
+            subprocess.CREATE_NO_WINDOW
+            | subprocess.CREATE_NEW_PROCESS_GROUP
+        )
+    else:
+        options["start_new_session"] = True
+    return options
+
+
 class _CacheService:
     def __init__(self, metadata: CacheMetadata) -> None:
         self.metadata = metadata
@@ -921,11 +936,7 @@ def _start_cache_unlocked(
     ]
     if project:
         command.extend(("--project-file", project))
-    options: dict[str, object] = {"stdin": subprocess.DEVNULL, "stdout": subprocess.DEVNULL}
-    if os.name == "nt":
-        options["creationflags"] = subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
-    else:
-        options["start_new_session"] = True
+    options = _daemon_process_options()
     with tempfile.TemporaryFile() as diagnostics:
         options["stderr"] = diagnostics
         process = subprocess.Popen(command, **options)

{python_delphi_lsp-2.3.1 → python_delphi_lsp-2.3.2}/delphi_lsp/agent_cli.py

@@ -151,7 +151,14 @@ def build_parser() -> argparse.ArgumentParser:
 
 def _add_cache_start_arguments(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--root", type=Path, default=Path("."))
-    parser.add_argument("--project-file", type=Path)
+    parser.add_argument(
+        "--project-file",
+        type=Path,
+        help=(
+            "Optionally select a .dproj, .dpr, or .dpk file, relative to "
+            "--root if needed."
+        ),
+    )
     parser.add_argument("--max-memory", type=parse_memory_size, default=DEFAULT_MAX_MEMORY_BYTES)
     parser.add_argument("--workers", type=parse_worker_setting, default=0)
     parser.add_argument("--idle-timeout", type=_positive_integer, default=DEFAULT_IDLE_TIMEOUT)

{python_delphi_lsp-2.3.1 → python_delphi_lsp-2.3.2}/delphi_lsp/agent_context.py

@@ -853,6 +853,7 @@ class AgentContext:
             )
         elif request.project_id:
             self._focus = Focus(project_id=self._workspace.active_project_id)
+            self._require_registry(revision)
         return self._response(request, revision, [self._focus.to_mapping()])
 
     def _handle_metrics(self, request: AgentRequest, revision: str) -> AgentResponse:
@@ -992,7 +993,8 @@ class AgentContext:
         if not project_id:
             raise AgentProtocolError(
                 "project_required",
-                "Select a project before querying symbols.",
+                "Multiple projects were found. Run 'query open', then select one "
+                "with 'query focus --project-id PROJECT_ID'.",
             )
         return project_id
 

{python_delphi_lsp-2.3.1 → python_delphi_lsp-2.3.2}/delphi_lsp/agent_templates.py

@@ -220,7 +220,7 @@ Inspect Delphi/Object Pascal only through `delphi_codebase`; never raw bash/read
 
 ## Protocol v2 workflow
 
-1. Call `open`. If the requested project is not active, select it with `focus(project_id)`.
+1. Call `open`. A multi-project repository is active as one workspace by default; select a concrete project with `focus(project_id)` only when project-specific compiler context is needed.
 2. Call `find` with a narrow query, then `focus(target_id)` for the returned target.
 3. Inspect focused details in this order as needed: `summary`, `declaration`, `members`, `context`, `body`, `implementations`.
 4. Trace relations with `references`, `callers`, `callees`, `uses`, `used_by`, `inherits`, or `implements`.

{python_delphi_lsp-2.3.1 → python_delphi_lsp-2.3.2}/delphi_lsp/agent_workspace.py

@@ -112,6 +112,21 @@ class AgentWorkspace:
         )
         projects: list[AgentProject] = []
         project_paths: dict[str, Path | None] = {}
+        default_project_id = ""
+        if (
+            resolved_project_file is None
+            and len(discovery.project_files) > 1
+        ):
+            default_project_id = make_target_id("project", "", "workspace")
+            projects.append(
+                AgentProject(
+                    project_id=default_project_id,
+                    name="Workspace",
+                    path=".",
+                    kind="workspace",
+                )
+            )
+            project_paths[default_project_id] = None
         if discovery.project_files:
             for value in discovery.project_files:
                 path = Path(value)
@@ -140,7 +155,9 @@ class AgentWorkspace:
             project_paths[project_id] = None
 
         workspace = cls(root_path, discovery, tuple(projects), project_paths)
-        if len(projects) == 1:
+        if default_project_id:
+            workspace.select_project(default_project_id)
+        elif len(projects) == 1:
             workspace.select_project(projects[0].project_id)
         return workspace
 
@@ -305,7 +322,11 @@ class AgentWorkspace:
         project_path = self._project_paths[project_id]
         cached = self._project_cache.get(project_id)
         if project_path is None:
-            discovery = self._discovery if cached is None else discover_workspace_sources(self._root)
+            discovery = (
+                self._discovery
+                if cached is None and self._discovery.source_files
+                else discover_workspace_sources(self._root)
+            )
         else:
             discovery = discover_delphi_project(
                 self._root,

{python_delphi_lsp-2.3.1 → python_delphi_lsp-2.3.2}/delphi_lsp/project_discovery.py

@@ -146,7 +146,21 @@ def discover_delphi_project(
     for value in defines:
         add_define(value)
 
-    candidates = _project_candidates(root_path, project_path)
+    explicit_dproj: Path | None = None
+    if (
+        project_path is not None
+        and project_path.suffix.casefold() == ".dproj"
+    ):
+        explicit_dproj = project_path
+        project_path = _project_entry_from_dproj(
+            explicit_dproj,
+            discovery,
+        )
+    candidates = (
+        []
+        if explicit_dproj is not None and project_path is None
+        else _project_candidates(root_path, project_path)
+    )
     for project in candidates:
         key = str(project).casefold()
         if key not in seen_projects:
@@ -160,8 +174,13 @@ def discover_delphi_project(
                 seen_search,
                 discovery.search_path_origins,
             )
-        dproj = project.with_suffix(".dproj")
-        if dproj.exists():
+        dproj_candidates = [project.with_suffix(".dproj")]
+        if explicit_dproj is not None:
+            dproj_candidates.insert(0, explicit_dproj)
+        for dproj in dproj_candidates:
+            config_key = str(dproj).casefold()
+            if config_key in seen_configs or not dproj.exists():
+                continue
             _read_dproj(
                 dproj,
                 discovery,
@@ -173,7 +192,7 @@ def discover_delphi_project(
                 discovery.include_path_origins,
                 add_define,
             )
-            seen_configs.add(str(dproj).casefold())
+            seen_configs.add(config_key)
             discovery.config_files.append(str(dproj))
         for cfg in (project.with_suffix(".cfg"), project.with_suffix(".dof")):
             if cfg.exists():
@@ -483,6 +502,72 @@ def _main_source_from_dproj(path: Path) -> str | None:
     return None
 
 
+def _project_entry_from_dproj(
+    path: Path,
+    discovery: DelphiProjectDiscovery,
+) -> Path | None:
+    try:
+        root = ET.parse(path).getroot()
+    except ET.ParseError as exc:
+        discovery.problems.append(
+            DiscoveryProblem(
+                "cant_read_project",
+                f"Could not parse Delphi project file: {exc}",
+                str(path),
+            )
+        )
+        return None
+    except OSError as exc:
+        discovery.problems.append(
+            DiscoveryProblem(
+                "cant_read_project",
+                f"Could not read Delphi project file: {exc}",
+                str(path),
+            )
+        )
+        return None
+
+    main_source = next(
+        (
+            (element.text or "").strip()
+            for element in root.iter()
+            if _xml_local_name(element.tag) == "MainSource"
+            and (element.text or "").strip()
+        ),
+        "",
+    )
+    if not main_source:
+        discovery.problems.append(
+            DiscoveryProblem(
+                "cant_read_project",
+                "Delphi project file does not define MainSource.",
+                str(path),
+            )
+        )
+        return None
+
+    entry = (path.parent / main_source).resolve()
+    if entry.suffix.casefold() not in PROJECT_EXTENSIONS:
+        discovery.problems.append(
+            DiscoveryProblem(
+                "cant_read_project",
+                "MainSource must reference a .dpr or .dpk entry file.",
+                str(path),
+            )
+        )
+        return None
+    if not entry.is_file():
+        discovery.problems.append(
+            DiscoveryProblem(
+                "cant_read_project",
+                f"MainSource does not exist: {entry}",
+                str(path),
+            )
+        )
+        return None
+    return entry
+
+
 def _scan_sources(
     root: Path,
     discovery: DelphiProjectDiscovery,

{python_delphi_lsp-2.3.1 → python_delphi_lsp-2.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-delphi-lsp"
-version = "2.3.1"
+version = "2.3.2"
 description = "Python Delphi/Object Pascal parser, semantic indexer, and language server."
 readme = "README.md"
 requires-python = ">=3.10"

{python_delphi_lsp-2.3.1 → python_delphi_lsp-2.3.2/python_delphi_lsp.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-delphi-lsp
-Version: 2.3.1
+Version: 2.3.2
 Summary: Python Delphi/Object Pascal parser, semantic indexer, and language server.
 Author: Dark Light
 License-Expression: MPL-2.0
@@ -42,7 +42,7 @@ Dynamic: license-file
 
 `python-delphi-lsp` parses Delphi/Object Pascal, builds semantic and project
 indexes, serves LSP, and provides bounded codebase navigation for agents.
-Version 2.3.1 is authored by Dark Light and supports Windows, macOS, and Linux.
+Version 2.3.2 is authored by Dark Light and supports Windows, macOS, and Linux.
 
 ## Install and quick start
 
@@ -166,7 +166,8 @@ available without returning the complete file as agent context.
 Auto-discovery reads `.dpr`, `.dpk`, `.dproj`, `.cfg`, and `.dof` files.
 Its resolution order is:
 
-1. An explicit project selection takes precedence.
+1. An explicit `.dproj`, `.dpr`, or `.dpk` selection takes precedence. An
+   explicit `.dproj` resolves its `MainSource`.
 2. Otherwise, `.dpr` and `.dpk` candidates are considered.
 3. `MainSource` in a `.dproj` contributes its entry project.
 4. A selected entry associates same-stem `.dproj`, `.cfg`, and `.dof`.
@@ -175,11 +176,13 @@ Its resolution order is:
 6. Direct `Unit in 'path/Unit.pas'` references contribute their parent
    directory to unit search paths.
 
-A single discovered project is selected automatically. With no project entry,
-the server uses a synthetic workspace of supported sources. Scans skip build
-and cache directories such as `build`, `dist`, environments, VCS folders,
-`node_modules`, and tool caches. Missing paths and invalid metadata become
-problems; paths are not guessed.
+A single discovered project is selected automatically. With multiple project
+entries, a synthetic repository workspace containing every supported source is
+selected automatically while the concrete projects remain available. With no
+project entry, the same workspace model is used. Scans skip build and cache
+directories such as `build`, `dist`, environments, VCS folders, `node_modules`,
+and tool caches. Missing paths and invalid metadata become problems; paths are
+not guessed.
 
 ## Agent CLI and Interface/Protocol v2
 
@@ -197,7 +200,7 @@ delphi-lsp-agent view --root PATH [--project-file FILE] --layer LAYER
 delphi-lsp-agent index --root PATH [--project-file FILE] [--out FILE]
                        [--workers auto|N]
 delphi-lsp-agent query --root PATH ACTION [VALUE]
-                      [--project-id FILE] [--detail summary|declaration|members|context|body|implementations]
+                      [--project-id ID] [--detail summary|declaration|members|context|body|implementations]
                       [--relation references|callers|callees|uses|used_by|inherits|implements]
                       [--cursor TEXT] [--max-items INT] [--max-chars INT]
 delphi-lsp-agent skill install [--target PATH] [--force]
@@ -229,6 +232,32 @@ delphi-lsp-agent query --root PATH metrics UNIT_QUERY
 delphi-lsp-agent cache status --root PATH --format json
 ```
 
+The repository root is sufficient even when it contains many projects:
+
+```bash
+delphi-lsp-agent cache start --root PATH
+delphi-lsp-agent query --root PATH find TCustomer
+```
+
+This prewarms one bounded repository navigation index and requires no project
+selection. A `.dproj` is optional. Pass one when its project-specific compiler
+settings and `MainSource` should define the index:
+
+```bash
+delphi-lsp-agent cache start --root PATH --project-file relative/path/Main.dproj
+```
+
+An explicit `.dpr` or `.dpk` remains supported. To switch an already running
+repository cache to one of its concrete project views, list the projects and
+focus one by its returned `project_id`:
+
+```bash
+delphi-lsp-agent query --root PATH open
+delphi-lsp-agent query --root PATH focus --project-id PROJECT_ID
+```
+
+Selecting a project this way also prewarms its navigation cache.
+
 `inspect` uses the currently focused target, so call `focus TARGET_ID` before
 `inspect` unless a previous request already selected it.
 

{python_delphi_lsp-2.3.1 → python_delphi_lsp-2.3.2}/tests/test_agent_cache.py

@@ -332,6 +332,45 @@ def test_startup_timeout_replaces_the_old_ten_second_deadline(
     assert process.killed is True
 
 
+def test_windows_cache_daemon_starts_without_a_console_window(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    from delphi_lsp import agent_cache
+
+    create_no_window = 0x08000000
+    create_new_process_group = 0x00000200
+    detached_process = 0x00000008
+    monkeypatch.setattr(agent_cache.os, "name", "nt")
+    monkeypatch.setattr(
+        agent_cache.subprocess,
+        "CREATE_NO_WINDOW",
+        create_no_window,
+        raising=False,
+    )
+    monkeypatch.setattr(
+        agent_cache.subprocess,
+        "CREATE_NEW_PROCESS_GROUP",
+        create_new_process_group,
+        raising=False,
+    )
+    monkeypatch.setattr(
+        agent_cache.subprocess,
+        "DETACHED_PROCESS",
+        detached_process,
+        raising=False,
+    )
+
+    options = agent_cache._daemon_process_options()
+
+    assert options["creationflags"] == (
+        create_no_window | create_new_process_group
+    )
+    assert options["creationflags"] & detached_process == 0
+    assert options["stdin"] is agent_cache.subprocess.DEVNULL
+    assert options["stdout"] is agent_cache.subprocess.DEVNULL
+    assert "start_new_session" not in options
+
+
 @pytest.mark.parametrize("startup_timeout", [0, -1, float("nan"), float("inf")])
 def test_start_cache_rejects_non_positive_startup_timeout(
     tmp_path: Path,
@@ -453,6 +492,72 @@ def test_prewarm_only_tolerates_project_selection_error(monkeypatch, tmp_path: P
         service.prewarm()
 
 
+def test_multiple_projects_prewarm_repository_navigation_cache(
+    tmp_path: Path,
+) -> None:
+    from delphi_lsp.agent_cache import CacheMetadata, _CacheService
+
+    write_source(
+        tmp_path / "A.dpr",
+        "program A; uses AUnit in 'AUnit.pas'; begin end.",
+    )
+    write_source(
+        tmp_path / "B.dpr",
+        "program B; uses BUnit in 'BUnit.pas'; begin end.",
+    )
+    write_source(
+        tmp_path / "AUnit.pas",
+        """
+        unit AUnit;
+        interface
+        type
+          TARepositoryCache = class
+          end;
+        implementation
+        end.
+        """,
+    )
+    write_source(
+        tmp_path / "BUnit.pas",
+        """
+        unit BUnit;
+        interface
+        type
+          TBRepositoryCache = class
+          end;
+        implementation
+        end.
+        """,
+    )
+    metadata = CacheMetadata(
+        2,
+        str(tmp_path.resolve()),
+        os.getpid(),
+        1,
+        "x" * 32,
+        "test",
+        "",
+        512 * 1024**2,
+        0,
+        10,
+        time.time(),
+    )
+    service = _CacheService(metadata)
+
+    service.prewarm()
+
+    assert service.context.navigation_cache_is_warm
+    assert service.cache_state == "warm"
+    assert service.status()["current_bytes"] > 0
+    result = service.request(
+        {"action": "find", "query": "RepositoryCache"}
+    ).payload["result"]
+    assert {item["name"] for item in result} == {
+        "TARepositoryCache",
+        "TBRepositoryCache",
+    }
+
+
 def test_cache_service_uses_constant_time_accounting_instead_of_deep_graph_walk(
     monkeypatch: pytest.MonkeyPatch,
     tmp_path: Path,
@@ -735,6 +840,7 @@ def test_readme_documents_bounded_cache_daemon_commands_and_retention_contract()
         "delphi-lsp-agent cache stop --root PATH",
         "delphi-lsp-agent query --root PATH find TCustomer",
         "delphi-lsp-agent query --root PATH focus TARGET_ID",
+        "delphi-lsp-agent query --root PATH focus --project-id PROJECT_ID",
         "delphi-lsp-agent query --root PATH inspect",
         "delphi-lsp-agent query --root PATH trace TARGET_ID --relation callers",
         "delphi-lsp-agent query --root PATH metrics UNIT_QUERY",
@@ -755,6 +861,8 @@ def test_readme_documents_bounded_cache_daemon_commands_and_retention_contract()
     assert "status JSON" in readme
     assert "Protocol v2 JSON" in readme
     assert "writes warnings to stderr" in readme
+    assert "A `.dproj` is optional" in readme
+    assert "Selecting a project this way also prewarms" in readme
     assert "Eviction is ordered" in readme
     assert "auxiliary caches are evicted first" in readme
     assert "rebuilds the navigation state on demand" in readme

{python_delphi_lsp-2.3.1 → python_delphi_lsp-2.3.2}/tests/test_agent_cli_errors.py

@@ -64,6 +64,18 @@ def test_query_cli_rejects_protocol_limits_before_contacting_cache(
         parser.parse_args(["query", "open", option, value])
 
 
+def test_cache_start_help_documents_optional_dproj(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    parser = agent_cli.build_parser()
+
+    with pytest.raises(SystemExit) as stopped:
+        parser.parse_args(["cache", "start", "--help"])
+
+    assert stopped.value.code == 0
+    assert ".dproj" in capsys.readouterr().out
+
+
 @pytest.mark.parametrize("value", [0, -1, True])
 def test_start_cache_rejects_non_positive_idle_timeout(
     tmp_path: Path,