python-delphi-lsp 2.3.0__py3-none-any.whl → 2.3.2__py3-none-any.whl

delphi_lsp/_version.py

@@ -1 +1 @@
-__version__ = "2.3.0"
+__version__ = "2.3.2"

delphi_lsp/agent_cache.py

@@ -45,6 +45,88 @@ _WATCHED_SUFFIXES = frozenset(
 )
 
 
+def current_process_rss_bytes() -> int:
+    """Return the current resident set size, or zero when unavailable."""
+    try:
+        if sys.platform == "darwin":
+            return _darwin_process_rss_bytes()
+        if sys.platform.startswith("linux"):
+            statm = Path("/proc/self/statm").read_text(encoding="ascii").split()
+            return int(statm[1]) * int(os.sysconf("SC_PAGE_SIZE"))
+        if os.name == "nt":
+            return _windows_process_rss_bytes()
+    except Exception:
+        pass
+    return 0
+
+
+def _darwin_process_rss_bytes() -> int:
+    import ctypes
+
+    class TimeValue(ctypes.Structure):
+        _fields_ = [("seconds", ctypes.c_int), ("microseconds", ctypes.c_int)]
+
+    class MachTaskBasicInfo(ctypes.Structure):
+        _fields_ = [
+            ("virtual_size", ctypes.c_uint64),
+            ("resident_size", ctypes.c_uint64),
+            ("resident_size_max", ctypes.c_uint64),
+            ("user_time", TimeValue),
+            ("system_time", TimeValue),
+            ("policy", ctypes.c_int),
+            ("suspend_count", ctypes.c_int),
+        ]
+
+    library = ctypes.CDLL(None)
+    library.mach_task_self.restype = ctypes.c_uint
+    library.task_info.argtypes = (
+        ctypes.c_uint,
+        ctypes.c_int,
+        ctypes.c_void_p,
+        ctypes.POINTER(ctypes.c_uint),
+    )
+    library.task_info.restype = ctypes.c_int
+    info = MachTaskBasicInfo()
+    count = ctypes.c_uint(ctypes.sizeof(info) // ctypes.sizeof(ctypes.c_int))
+    result = library.task_info(
+        library.mach_task_self(),
+        20,
+        ctypes.byref(info),
+        ctypes.byref(count),
+    )
+    return int(info.resident_size) if result == 0 else 0
+
+
+def _windows_process_rss_bytes() -> int:
+    import ctypes
+    from ctypes import wintypes
+
+    class ProcessMemoryCounters(ctypes.Structure):
+        _fields_ = [
+            ("cb", wintypes.DWORD),
+            ("PageFaultCount", wintypes.DWORD),
+            ("PeakWorkingSetSize", ctypes.c_size_t),
+            ("WorkingSetSize", ctypes.c_size_t),
+            ("QuotaPeakPagedPoolUsage", ctypes.c_size_t),
+            ("QuotaPagedPoolUsage", ctypes.c_size_t),
+            ("QuotaPeakNonPagedPoolUsage", ctypes.c_size_t),
+            ("QuotaNonPagedPoolUsage", ctypes.c_size_t),
+            ("PagefileUsage", ctypes.c_size_t),
+            ("PeakPagefileUsage", ctypes.c_size_t),
+        ]
+
+    counters = ProcessMemoryCounters()
+    counters.cb = ctypes.sizeof(counters)
+    process = ctypes.windll.kernel32.GetCurrentProcess()
+    if not ctypes.windll.psapi.GetProcessMemoryInfo(
+        process,
+        ctypes.byref(counters),
+        counters.cb,
+    ):
+        return 0
+    return int(counters.WorkingSetSize)
+
+
 def estimate_deep_size(value: object) -> int:
     """Estimate the memory retained by an owned object graph.
 
@@ -292,6 +374,11 @@ def _safe_navigation_cache_path(root: str | Path, *, create: bool = False) -> Pa
     return result
 
 
+def navigation_cache_path(root: str | Path, *, create: bool = False) -> Path:
+    """Return the validated persistent navigation-cache directory."""
+    return _safe_navigation_cache_path(root, create=create)
+
+
 def _metadata_mapping(metadata: CacheMetadata) -> dict[str, object]:
     return {field.name: getattr(metadata, field.name) for field in fields(metadata)}
 
@@ -552,16 +639,32 @@ 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
+        self._rss_baseline_bytes = current_process_rss_bytes()
         self.context = AgentContext.open(
             metadata.root,
             metadata.project_file or None,
             workers=metadata.workers,
             worker_memory_budget_bytes=metadata.max_memory_bytes,
             revision_check_interval_seconds=_CACHE_REVISION_CHECK_INTERVAL_SECONDS,
-            navigation_cache_dir=_safe_navigation_cache_path(
+            navigation_cache_dir=navigation_cache_path(
                 metadata.root,
                 create=True,
             ),
@@ -577,6 +680,15 @@ class _CacheService:
         self.prewarm_seconds = 0.0
         self.shutdown = threading.Event()
 
+    def _measure_retained_bytes(self) -> int:
+        process_rss = current_process_rss_bytes()
+        process_growth = (
+            max(0, process_rss - self._rss_baseline_bytes)
+            if process_rss > 0 and self._rss_baseline_bytes > 0
+            else 0
+        )
+        return max(self.context.estimated_cache_bytes, process_growth)
+
     def prewarm(self) -> None:
         started = time.monotonic()
         try:
@@ -587,7 +699,7 @@ class _CacheService:
                 raise
             self.cache_state = "ready"
         self.last_budget = self.budget.enforce(
-            measure=lambda: self.context.estimated_cache_bytes,
+            measure=self._measure_retained_bytes,
             evict_auxiliary=self.context.evict_auxiliary_caches,
             evict_navigation=self.context.evict_navigation_caches,
         )
@@ -628,7 +740,7 @@ class _CacheService:
             if before != after:
                 self.stats.invalidations += 1
             self.last_budget = self.budget.enforce(
-                measure=lambda: self.context.estimated_cache_bytes,
+                measure=self._measure_retained_bytes,
                 evict_auxiliary=self.context.evict_auxiliary_caches,
                 evict_navigation=self.context.evict_navigation_caches,
             )
@@ -675,21 +787,34 @@ def _watch_filter(_change: object, path: str) -> bool:
     return Path(path).suffix.casefold() in _WATCHED_SUFFIXES
 
 
-def _watch_workspace(service: _CacheService) -> None:
+def watch_workspace_changes(
+    root: str | Path,
+    *,
+    stop_event: threading.Event,
+    on_change: Callable[[], None],
+) -> None:
     try:
         for changes in watch(
-            service.metadata.root,
+            root,
             watch_filter=_watch_filter,
-            stop_event=service.shutdown,
+            stop_event=stop_event,
             debounce=50,
             step=20,
             recursive=True,
             raise_interrupt=False,
         ):
             if changes:
-                service.context.invalidate_revision_cache()
+                on_change()
     except (OSError, RuntimeError):
-        service.context.invalidate_revision_cache()
+        on_change()
+
+
+def _watch_workspace(service: _CacheService) -> None:
+    watch_workspace_changes(
+        service.metadata.root,
+        stop_event=service.shutdown,
+        on_change=service.context.invalidate_revision_cache,
+    )
 
 
 def _serve_connection(connection: socket.socket, service: _CacheService) -> None:
@@ -811,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)
@@ -867,6 +988,8 @@ def start_cache(
 ) -> CacheMetadata:
     if type(workers) is not int or not 0 <= workers <= 32:
         raise ValueError("workers must be auto or an integer from 1 through 32.")
+    if type(idle_timeout) is not int or idle_timeout <= 0:
+        raise ValueError("idle_timeout must be greater than zero.")
     if not math.isfinite(startup_timeout) or startup_timeout <= 0:
         raise ValueError("startup_timeout must be greater than zero.")
     with _start_lock(root, startup_timeout):
@@ -930,7 +1053,7 @@ def main(argv: list[str] | None = None) -> int:
     serve.add_argument("--project-file", default="")
     serve.add_argument("--max-memory", type=int, default=DEFAULT_MAX_MEMORY_BYTES)
     serve.add_argument("--workers", type=int, default=0)
-    serve.add_argument("--idle-timeout", type=int, default=DEFAULT_IDLE_TIMEOUT)
+    serve.add_argument("--idle-timeout", type=_positive_integer, default=DEFAULT_IDLE_TIMEOUT)
     args = parser.parse_args(argv)
     if args.command == "serve":
         run_cache_daemon(
@@ -943,5 +1066,12 @@ def main(argv: list[str] | None = None) -> int:
     return 0
 
 
+def _positive_integer(value: str) -> int:
+    parsed = int(value)
+    if parsed <= 0:
+        raise argparse.ArgumentTypeError("value must be greater than zero")
+    return parsed
+
+
 if __name__ == "__main__":
     raise SystemExit(main())

delphi_lsp/agent_cli.py

@@ -5,6 +5,7 @@ import json
 import math
 import os
 import sys
+import threading
 from pathlib import Path
 from typing import BinaryIO, TextIO
 
@@ -15,15 +16,17 @@ from .agent_cache import (
     DEFAULT_MAX_MEMORY_BYTES,
     DEFAULT_STARTUP_TIMEOUT,
     parse_memory_size,
+    navigation_cache_path,
     query_cache,
     run_cache_daemon,
     start_cache,
     stop_cache,
+    watch_workspace_changes,
 )
 from .agent_layers import build_codebase_index, layer_payload, render_layer
 from .agent_protocol import AgentProtocolError, SUPPORTED_ACTIONS, SUPPORTED_DETAILS, SUPPORTED_RELATIONS
 from .agent_templates import install_opencode_support, install_skill
-from .parallel_outline import parse_worker_setting
+from .parallel_outline import ParallelOutlineError, parse_worker_setting
 
 
 _MAX_WORKER_RECORD_BYTES = 1024 * 1024
@@ -32,6 +35,14 @@ _INVALID_ENCODING_MESSAGE = "Invalid UTF-8 request."
 _REQUEST_TOO_LARGE_MESSAGE = "Request exceeds the 1 MiB limit."
 _INTERNAL_ERROR_MESSAGE = "Internal request error."
 _SOURCE_UNAVAILABLE_MESSAGE = "Selected source is unavailable."
+_WORKER_REVISION_CHECK_INTERVAL_SECONDS = 30.0
+
+
+class _CliError(RuntimeError):
+    def __init__(self, code: str, message: str) -> None:
+        self.code = code
+        self.message = message
+        super().__init__(message)
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -120,7 +131,7 @@ def build_parser() -> argparse.ArgumentParser:
     cache_serve.add_argument("--project-file", type=Path)
     cache_serve.add_argument("--max-memory", type=parse_memory_size, required=True)
     cache_serve.add_argument("--workers", type=parse_worker_setting, required=True)
-    cache_serve.add_argument("--idle-timeout", type=int, required=True)
+    cache_serve.add_argument("--idle-timeout", type=_positive_integer, required=True)
     cache_serve.set_defaults(func=_cache_serve)
 
     query = subcommands.add_parser("query", help="Send an ergonomic request to a running cache daemon.")
@@ -131,8 +142,8 @@ def build_parser() -> argparse.ArgumentParser:
     query.add_argument("--detail", choices=SUPPORTED_DETAILS, default="summary")
     query.add_argument("--relation", choices=SUPPORTED_RELATIONS)
     query.add_argument("--cursor", default="")
-    query.add_argument("--max-items", type=int, default=12)
-    query.add_argument("--max-chars", type=int, default=12000)
+    query.add_argument("--max-items", type=_max_items, default=12)
+    query.add_argument("--max-chars", type=_max_chars, default=12000)
     query.set_defaults(func=_query)
 
     return parser
@@ -140,10 +151,17 @@ 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=int, default=DEFAULT_IDLE_TIMEOUT)
+    parser.add_argument("--idle-timeout", type=_positive_integer, default=DEFAULT_IDLE_TIMEOUT)
     parser.add_argument("--startup-timeout", type=_positive_float, default=DEFAULT_STARTUP_TIMEOUT)
 
 
@@ -154,6 +172,27 @@ def _positive_float(value: str) -> float:
     return parsed
 
 
+def _positive_integer(value: str) -> int:
+    parsed = int(value)
+    if parsed <= 0:
+        raise argparse.ArgumentTypeError("value must be greater than zero")
+    return parsed
+
+
+def _max_items(value: str) -> int:
+    parsed = int(value)
+    if not 1 <= parsed <= 50:
+        raise argparse.ArgumentTypeError("value must be between 1 and 50")
+    return parsed
+
+
+def _max_chars(value: str) -> int:
+    parsed = int(value)
+    if not 256 <= parsed <= 40000:
+        raise argparse.ArgumentTypeError("value must be between 256 and 40000")
+    return parsed
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = build_parser()
     args = parser.parse_args(argv)
@@ -161,9 +200,23 @@ def main(argv: list[str] | None = None) -> int:
         result = args.func(args)
         if not getattr(sys.stdout, "closed", False):
             sys.stdout.flush()
+    except _CliError as error:
+        sys.stderr.write(f"cli_error:{error.code}: {error.message}\n")
+        sys.stderr.flush()
+        return 1
+    except CacheClientError as error:
+        return _cache_error(error)
+    except ParallelOutlineError as error:
+        sys.stderr.write(f"cli_error:parallel_failed: {error}\n")
+        sys.stderr.flush()
+        return 1
     except BrokenPipeError:
         _discard_broken_stdout()
         os._exit(1)
+    except OSError as error:
+        sys.stderr.write(f"cli_error:io_error: {error}\n")
+        sys.stderr.flush()
+        return 1
     return result if isinstance(result, int) else 0
 
 
@@ -189,6 +242,7 @@ def _discard_broken_stdout() -> None:
 
 
 def _view(args: argparse.Namespace) -> None:
+    args.root = _workspace_root(args.root)
     index = build_codebase_index(
         args.root,
         project_file=args.project_file,
@@ -199,6 +253,7 @@ def _view(args: argparse.Namespace) -> None:
 
 
 def _index(args: argparse.Namespace) -> None:
+    args.root = _workspace_root(args.root)
     index = build_codebase_index(
         args.root,
         project_file=args.project_file,
@@ -216,33 +271,72 @@ def _index(args: argparse.Namespace) -> None:
 
 
 def _skill_install(args: argparse.Namespace) -> None:
-    skill_path = install_skill(args.target, force=args.force)
+    try:
+        skill_path = install_skill(args.target, force=args.force)
+    except FileExistsError as error:
+        raise _CliError("install_conflict", str(error)) from None
     print(skill_path)
 
 
 def _opencode_install(args: argparse.Namespace) -> None:
-    skill_path, plugin_path, agent_path = install_opencode_support(
-        args.target,
-        python_executable=args.python,
-        force=args.force,
-        write_config=args.write_config,
-    )
+    try:
+        skill_path, plugin_path, agent_path = install_opencode_support(
+            args.target,
+            python_executable=args.python,
+            force=args.force,
+            write_config=args.write_config,
+        )
+    except FileExistsError as error:
+        raise _CliError("install_conflict", str(error)) from None
     print(skill_path)
     print(plugin_path)
     print(agent_path)
 
 
 def _worker(args: argparse.Namespace) -> None:
-    context = AgentContext.open(args.root, args.project_file, workers=args.workers)
+    args.root = _workspace_root(args.root)
+    context = _open_worker_context(args.root, args.project_file, args.workers)
+    watcher_stop = threading.Event()
+    watcher = threading.Thread(
+        target=watch_workspace_changes,
+        kwargs={
+            "root": args.root,
+            "stop_event": watcher_stop,
+            "on_change": context.invalidate_revision_cache,
+        },
+        name="delphi-worker-watcher",
+        daemon=True,
+    )
+    watcher.start()
     try:
         _serve_worker(context, sys.stdin.buffer, sys.stdout.buffer, sys.stderr)
     finally:
+        watcher_stop.set()
+        watcher.join(timeout=2.0)
         try:
             sys.stdout.close()
         except (BrokenPipeError, OSError) as error:
             raise BrokenPipeError from error
 
 
+def _open_worker_context(
+    root: Path,
+    project_file: Path | None,
+    workers: int,
+) -> AgentContext:
+    try:
+        cache_dir: Path | None = navigation_cache_path(root, create=True)
+    except (CacheClientError, OSError):
+        cache_dir = None
+    return AgentContext.open(
+        root,
+        project_file,
+        workers=workers,
+        revision_check_interval_seconds=_WORKER_REVISION_CHECK_INTERVAL_SECONDS,
+        navigation_cache_dir=cache_dir,
+    )
+
+
 def _write_json(payload: object) -> None:
     sys.stdout.write(json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + "\n")
 
@@ -260,6 +354,7 @@ def _cache_error(error: CacheClientError) -> int:
 
 
 def _cache_start(args: argparse.Namespace) -> int:
+    args.root = _workspace_root(args.root)
     try:
         start_cache(
             args.root,
@@ -278,6 +373,7 @@ def _cache_start(args: argparse.Namespace) -> int:
 
 
 def _cache_status(args: argparse.Namespace) -> int:
+    args.root = _workspace_root(args.root)
     try:
         response = query_cache(args.root, {"action": "status"})
     except CacheClientError as error:
@@ -295,6 +391,7 @@ def _cache_status(args: argparse.Namespace) -> int:
 
 
 def _cache_stop(args: argparse.Namespace) -> int:
+    args.root = _workspace_root(args.root)
     try:
         response = query_cache(args.root, {"action": "status"})
     except CacheClientError as error:
@@ -316,6 +413,7 @@ def _cache_stop(args: argparse.Namespace) -> int:
 
 
 def _cache_serve(args: argparse.Namespace) -> int:
+    args.root = _workspace_root(args.root)
     run_cache_daemon(
         args.root,
         project_file=str(args.project_file or ""),
@@ -327,6 +425,7 @@ def _cache_serve(args: argparse.Namespace) -> int:
 
 
 def _query(args: argparse.Namespace) -> int:
+    args.root = _workspace_root(args.root)
     request: dict[str, object] = {"action": args.action}
     if args.value:
         if args.action in {"find", "metrics"}:
@@ -350,6 +449,21 @@ def _query(args: argparse.Namespace) -> int:
     return 0
 
 
+def _workspace_root(value: str | Path) -> Path:
+    root = Path(value).expanduser()
+    if not root.exists():
+        raise _CliError(
+            "workspace_not_found",
+            f"Workspace root does not exist: {root}",
+        )
+    if not root.is_dir():
+        raise _CliError(
+            "workspace_not_directory",
+            f"Workspace root is not a directory: {root}",
+        )
+    return root.resolve()
+
+
 def _serve_worker(context: AgentContext, input_stream: BinaryIO, output_stream: BinaryIO, error_stream: TextIO) -> None:
     discarding_oversize_record = False
     while True:

delphi_lsp/agent_context.py

@@ -658,7 +658,7 @@ class AgentContext:
         return revision
 
     def invalidate_revision_cache(self) -> None:
-        self._last_revision_check_at = 0.0
+        self._last_revision_check_at = float("-inf")
 
     def handle(self, request: AgentRequest | Mapping[str, object]) -> AgentResponse:
         parsed = _validated_request(request)
@@ -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
 

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`.

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,

delphi_lsp/project_discovery.py

@@ -75,7 +75,11 @@ def discover_delphi_project(
     on_progress: ProgressCallback | None = None,
 ) -> DelphiProjectDiscovery:
     root_path = Path(root).expanduser().resolve()
-    project_path = Path(project_file).expanduser().resolve() if project_file is not None else None
+    project_path = Path(project_file).expanduser() if project_file is not None else None
+    if project_path is not None:
+        if not project_path.is_absolute():
+            project_path = root_path / project_path
+        project_path = project_path.resolve()
     discovery = DelphiProjectDiscovery(root=str(root_path))
     _emit_progress(on_progress, "discovery", str(root_path), 0, 0, None, "project discovery started")
 
@@ -142,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:
@@ -156,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,
@@ -169,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():
@@ -479,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.0.dist-info → python_delphi_lsp-2.3.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-delphi-lsp
-Version: 2.3.0
+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.0 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.0.dist-info → python_delphi_lsp-2.3.2.dist-info}/RECORD

@@ -1,14 +1,14 @@
 delphi_lsp/__init__.py,sha256=mq3tF0NrXDgbkJXDuf5HhW6sOnmP7DQxs3zl8fGoAmo,3867
-delphi_lsp/_version.py,sha256=CpK8IH_dCUAwg9tqv7zm9FxbBFkxCnED1JUiRe7cftU,22
-delphi_lsp/agent_cache.py,sha256=FMAYleW1XlWchBtha6bBnkFQiAFt_nCcMp5S28zKcy8,35211
-delphi_lsp/agent_cli.py,sha256=J2zmZP2D28pXi7tx06YyEqKsojbXQcO0LdZx27kGJ1M,16311
-delphi_lsp/agent_context.py,sha256=K3gGmmVKpc5vysmztwdEjIEeWXGTSmQXr8S47uzcKgQ,97269
+delphi_lsp/_version.py,sha256=J4CRnpR3v72FGOMp8gqSua_XWZpAfXuqgVWiQFB-gTY,22
+delphi_lsp/agent_cache.py,sha256=Fz7iPA-q2i-SLMmy6FBFTeUJ7Jdd8idXY2maRnhajbY,39204
+delphi_lsp/agent_cli.py,sha256=6cb-cmRmjAyoTNh_CrR-VFUt-sFRNDiVFAmQIkX1DLc,19797
+delphi_lsp/agent_context.py,sha256=9mDtYjL3LJRlwTEpUQeQIhcBkwDxQltQudKxVYdw8wk,97409
 delphi_lsp/agent_layers.py,sha256=Waiwp47BuNxxwzM8EfGb0tvLSRn2udRHkTmuX2JE6cg,25658
 delphi_lsp/agent_metrics.py,sha256=Zh96_qlaDzJIW33XiCucvUeD-Y0zaNr52MRAdKMv9Hg,5217
 delphi_lsp/agent_protocol.py,sha256=RxUyWaL-ixYO3nvAY2Apkhs1c2r5oNEheUaw64Oizo4,12648
 delphi_lsp/agent_relations.py,sha256=q01Mi44m-COs0gDRJa1bTcc1U5M5JsTkQBw4GX1HLPA,43381
-delphi_lsp/agent_templates.py,sha256=LXtbAPj0Nxvp3ycZARPELEb51BFoi2vtiCe-pYHNteE,21834
-delphi_lsp/agent_workspace.py,sha256=LVcJ35LNIkXTIcbE-t46SBtBWWlyREROezhirlaswsE,25674
+delphi_lsp/agent_templates.py,sha256=8KuLxBbl76mXE-MzNqWVB7OXxiHVu52q17cRsf4nHr4,21930
+delphi_lsp/agent_workspace.py,sha256=si79CAn99nOodapE4ls0-EhClvl1FpLQ-bwWw0j_wf4,26385
 delphi_lsp/binary.py,sha256=s-c0tstGtkbjxgyiS6vteqh5D40qmVEenoECtBCsDcU,8495
 delphi_lsp/comment_builder.py,sha256=XvFW7WTbYy7yGN3MG40gtabTvhGj1ea1MYkySDbVMDA,832
 delphi_lsp/consts.py,sha256=qM40iwxXmvEileWHJVLMYlQSkLoLyQaqM-Zscz3VJbs,5958
@@ -27,16 +27,16 @@ delphi_lsp/parser.py,sha256=qYY_eTeGgLYn30QyN4_ERjU9-TLFuD5u_CXAMYJdX5A,7721
 delphi_lsp/parser_backend.py,sha256=_-veK3B4OreA5wkv5pm96-JTTZtNZUQ92JZMktp2tPU,1667
 delphi_lsp/preprocessor.py,sha256=0WsY4DuYCSo8FOe8TK_8Vo2z8nFhh1nut1OQaifrvgI,32037
 delphi_lsp/progress.py,sha256=FF3lqdDKLvq3b7cOhuSc3P0FDzVnX0miD8U8_3xt5iY,535
-delphi_lsp/project_discovery.py,sha256=UpezFlNJDaF5sW8tkG_HUxHpAULSf1GSWXJTlUF8vMM,20230
+delphi_lsp/project_discovery.py,sha256=xONO3Q7d2k-duNutn1vS3dknS8VmWR_guFhzZBS2XOQ,22852
 delphi_lsp/project_indexer.py,sha256=kaDbQixp4x2Z9LnzSNhyjdsWfyEFUmE8DSE3cgdL1ZQ,14435
 delphi_lsp/semantic.py,sha256=FZ9x_QsIS_u-1DlzVlYgRqH9gQZ5ySnDAD-xHwzblU8,9808
 delphi_lsp/semantic_builder.py,sha256=ulA7xHJpltjc6cTo5wh9yTcYazuIykM-YLMXD1h-wzk,58680
 delphi_lsp/source_reader.py,sha256=HWiw25sLVZ6s1GGpMl17uZ-o68HoxTEd3Z0__m1vsSE,520
 delphi_lsp/workspace.py,sha256=TU__SujItRlW8hB2kuYC7ZJx1WQVOj7frYxvo7rDqeI,2137
 delphi_lsp/writer.py,sha256=j-cnyiHFNOTFECL7Ehm-m43ye7ev7qFeCCscFMjrAOY,2503
-python_delphi_lsp-2.3.0.dist-info/licenses/LICENSE,sha256=-rPda9qyJvHAhjCx3ZF-Efy07F4eAg4sFvg6ChOGPoU,16726
-python_delphi_lsp-2.3.0.dist-info/METADATA,sha256=8DUvuIk9qZ9uos80JzdZSoSqXu33kmvHCx1tYgCJPIg,21104
-python_delphi_lsp-2.3.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-python_delphi_lsp-2.3.0.dist-info/entry_points.txt,sha256=rh_yGH7diowge_acQcST87A-ewH1QezEsAYC8T5ineY,103
-python_delphi_lsp-2.3.0.dist-info/top_level.txt,sha256=0Zp0sjw5Qtic3EQX9zNeegURga8NuXk6c2e9PN-3OTs,11
-python_delphi_lsp-2.3.0.dist-info/RECORD,,
+python_delphi_lsp-2.3.2.dist-info/licenses/LICENSE,sha256=-rPda9qyJvHAhjCx3ZF-Efy07F4eAg4sFvg6ChOGPoU,16726
+python_delphi_lsp-2.3.2.dist-info/METADATA,sha256=5t0-eIjD3lYNQBEkRC1GzDNrBdEpgaHS-LvQISTC8VI,22175
+python_delphi_lsp-2.3.2.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
+python_delphi_lsp-2.3.2.dist-info/entry_points.txt,sha256=rh_yGH7diowge_acQcST87A-ewH1QezEsAYC8T5ineY,103
+python_delphi_lsp-2.3.2.dist-info/top_level.txt,sha256=0Zp0sjw5Qtic3EQX9zNeegURga8NuXk6c2e9PN-3OTs,11
+python_delphi_lsp-2.3.2.dist-info/RECORD,,

{python_delphi_lsp-2.3.0.dist-info → python_delphi_lsp-2.3.2.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (83.0.0)
+Generator: setuptools (79.0.1)
 Root-Is-Purelib: true
 Tag: py3-none-any