python-delphi-lsp 2.3.3__py3-none-any.whl → 3.1.0__py3-none-any.whl

delphi_lsp/_version.py

@@ -1 +1 @@
-__version__ = "2.3.3"
+__version__ = "3.1.0"

delphi_lsp/agent_cache.py

@@ -40,9 +40,13 @@ _STARTUP_DIAGNOSTIC_BYTES = 16 * 1024
 _STARTUP_TOKEN_RE = re.compile(r"(?i)(token\b[^\n\r]*?:?\s*['\"]?[A-Za-z0-9_-]+['\"]?|\b[a-zA-Z0-9_-]{32,})")
 _START_LOCK_INCOMPLETE_GRACE_SECONDS = 1.0
 _CACHE_REVISION_CHECK_INTERVAL_SECONDS = 3600.0
+_WATCHER_READY_TIMEOUT_SECONDS = 1.0
+_WATCHER_READY_POLL_MILLISECONDS = 50
 _WATCHED_SUFFIXES = frozenset(
     {".pas", ".pp", ".inc", ".dpr", ".dpk", ".dproj", ".cfg"}
 )
+_PROCESS_START_LOCKS_GUARD = threading.Lock()
+_PROCESS_START_LOCKS: dict[str, tuple[threading.Lock, int]] = {}
 
 
 def current_process_rss_bytes() -> int:
@@ -578,6 +582,30 @@ def _start_lock(root: str | Path, timeout: float):
             pass
 
 
+@contextlib.contextmanager
+def _process_start_lock(root: str | Path):
+    canonical = str(Path(root).resolve())
+    with _PROCESS_START_LOCKS_GUARD:
+        lock, users = _PROCESS_START_LOCKS.get(
+            canonical,
+            (threading.Lock(), 0),
+        )
+        _PROCESS_START_LOCKS[canonical] = (lock, users + 1)
+    try:
+        with lock:
+            yield
+    finally:
+        with _PROCESS_START_LOCKS_GUARD:
+            current_lock, current_users = _PROCESS_START_LOCKS[canonical]
+            if current_users == 1:
+                del _PROCESS_START_LOCKS[canonical]
+            else:
+                _PROCESS_START_LOCKS[canonical] = (
+                    current_lock,
+                    current_users - 1,
+                )
+
+
 def _client_exchange(metadata: CacheMetadata, request: dict[str, object]) -> CacheClientResponse:
     try:
         with socket.create_connection(("127.0.0.1", metadata.port), timeout=2) as connection:
@@ -655,31 +683,55 @@ def _daemon_process_options() -> dict[str, object]:
 
 
 class _CacheService:
-    def __init__(self, metadata: CacheMetadata) -> None:
+    def __init__(
+        self,
+        metadata: CacheMetadata,
+        *,
+        defer_context: bool = False,
+    ) -> 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=navigation_cache_path(
-                metadata.root,
-                create=True,
-            ),
-        )
+        self._context: AgentContext | None = None
+        self.context_ready = threading.Event()
+        self.watcher_ready = threading.Event()
         self.budget = CacheBudget(metadata.max_memory_bytes)
         self.stats = CacheStats()
         self.lock = threading.Lock()
         self.started = time.monotonic()
         self.last_activity = self.started
         self.cache_state = "warming"
-        self.last_revision = self.context.workspace.workspace_revision
+        self.last_revision = ""
         self.last_budget = BudgetResult(0, 0.0, 0.0, False, False, False)
         self.prewarm_seconds = 0.0
+        self.startup_error = ""
         self.shutdown = threading.Event()
         self.prewarm_thread: threading.Thread | None = None
+        if not defer_context:
+            self._initialize_context()
+
+    @property
+    def context(self) -> AgentContext:
+        if self._context is None:
+            raise RuntimeError("Cache workspace is still being discovered.")
+        return self._context
+
+    def _initialize_context(self) -> AgentContext:
+        if self._context is None:
+            context = AgentContext.open(
+                self.metadata.root,
+                self.metadata.project_file or None,
+                workers=self.metadata.workers,
+                worker_memory_budget_bytes=self.metadata.max_memory_bytes,
+                revision_check_interval_seconds=_CACHE_REVISION_CHECK_INTERVAL_SECONDS,
+                navigation_cache_dir=navigation_cache_path(
+                    self.metadata.root,
+                    create=True,
+                ),
+            )
+            self._context = context
+            self.last_revision = context.workspace.workspace_revision
+        self.context_ready.set()
+        return self._context
 
     def _measure_retained_bytes(self) -> int:
         process_rss = current_process_rss_bytes()
@@ -692,8 +744,9 @@ class _CacheService:
 
     def prewarm(self) -> None:
         started = time.monotonic()
+        context = self._initialize_context()
         try:
-            self.last_revision = self.context.prewarm_navigation()
+            self.last_revision = context.prewarm_navigation()
             self.cache_state = "warm"
         except AgentProtocolError as error:
             if error.code != "project_required":
@@ -708,15 +761,24 @@ class _CacheService:
             self.stats.evictions += 1
             self.cache_state = "compact"
         self.prewarm_seconds = time.monotonic() - started
-        self.stats.parallel_fallbacks = self.context.parallel_stats.fallbacks
+        self.stats.parallel_fallbacks = context.parallel_stats.fallbacks
 
     def start_prewarm(self) -> None:
         def run() -> None:
             try:
                 with self.lock:
                     self.prewarm()
-            except Exception:
+            except Exception as error:
+                detail = _truncate_and_sanitize_startup_diagnostics(
+                    f"{type(error).__name__}: {error}".encode(
+                        "utf-8",
+                        "replace",
+                    )
+                )
+                self.startup_error = detail or type(error).__name__
                 self.cache_state = "failed"
+            finally:
+                self.context_ready.set()
 
         self.prewarm_thread = threading.Thread(
             target=run,
@@ -740,7 +802,16 @@ class _CacheService:
                 "Cache is still warming. Retry after cache status reports ready.",
             )
         if self.cache_state == "failed":
-            raise CacheClientError("cache_failed", "Cache warm-up failed.")
+            detail = (
+                f" {self.startup_error}"
+                if self.startup_error
+                else ""
+            )
+            raise CacheClientError(
+                "cache_failed",
+                f"Cache workspace discovery or warm-up failed.{detail}",
+            )
+        self.watcher_ready.wait(timeout=_WATCHER_READY_TIMEOUT_SECONDS)
         with self.lock:
             self.last_activity = time.monotonic()
             before = self.last_revision
@@ -784,6 +855,12 @@ class _CacheService:
     def status(self) -> dict[str, object]:
         now = time.monotonic()
         idle = max(0.0, now - self.last_activity)
+        context = self._context
+        parallel_stats = (
+            context.parallel_stats
+            if context is not None
+            else None
+        )
         return {
             "pid": self.metadata.pid, "root": self.metadata.root, "project_file": self.metadata.project_file,
             "version": self.metadata.version, "uptime": now - self.started, "idle_seconds": idle,
@@ -795,15 +872,18 @@ class _CacheService:
             "cache_state": self.cache_state, "requests": self.stats.requests, "warm_hits": self.stats.warm_hits,
             "rebuilds": self.stats.rebuilds, "invalidations": self.stats.invalidations, "evictions": self.stats.evictions,
             "workers_configured": "auto" if self.metadata.workers == 0 else self.metadata.workers,
-            "workers_effective": self.context.parallel_stats.effective_workers,
-            "parallel_files_completed": self.context.parallel_stats.files_completed,
+            "workers_effective": parallel_stats.effective_workers if parallel_stats else 0,
+            "parallel_files_completed": parallel_stats.files_completed if parallel_stats else 0,
             "prewarm_seconds": self.prewarm_seconds,
-            "parallel_seconds": self.context.parallel_stats.elapsed_seconds,
+            "parallel_seconds": parallel_stats.elapsed_seconds if parallel_stats else 0.0,
             "parallel_fallbacks": self.stats.parallel_fallbacks,
-            "navigation_disk_hits": self.context.navigation_disk_hits,
-            "navigation_disk_misses": self.context.navigation_disk_misses,
+            "navigation_disk_hits": context.navigation_disk_hits if context else 0,
+            "navigation_disk_misses": context.navigation_disk_misses if context else 0,
+            "cpg_cache_entries": context.cpg_cache_entries if context else 0,
+            "cpg_cache_bytes": context.cpg_cache_bytes if context else 0,
             "idle_timeout": self.metadata.idle_timeout, "idle_remaining": max(0.0, self.metadata.idle_timeout - idle),
             "workspace_revision": self.last_revision,
+            "startup_error": self.startup_error,
         }
 
 
@@ -816,7 +896,9 @@ def watch_workspace_changes(
     *,
     stop_event: threading.Event,
     on_change: Callable[[], None],
+    on_ready: Callable[[], None] | None = None,
 ) -> None:
+    ready = False
     try:
         for changes in watch(
             root,
@@ -824,20 +906,33 @@ def watch_workspace_changes(
             stop_event=stop_event,
             debounce=50,
             step=20,
+            rust_timeout=_WATCHER_READY_POLL_MILLISECONDS,
+            yield_on_timeout=True,
             recursive=True,
             raise_interrupt=False,
         ):
+            if not ready:
+                ready = True
+                if on_ready is not None:
+                    on_ready()
             if changes:
                 on_change()
     except (OSError, RuntimeError):
         on_change()
+    finally:
+        if not ready and on_ready is not None:
+            on_ready()
 
 
 def _watch_workspace(service: _CacheService) -> None:
+    service.context_ready.wait()
+    if service.shutdown.is_set() or service._context is None:
+        return
     watch_workspace_changes(
         service.metadata.root,
         stop_event=service.shutdown,
-        on_change=service.context.invalidate_revision_cache,
+        on_change=service._context.invalidate_revision_cache,
+        on_ready=service.watcher_ready.set,
     )
 
 
@@ -888,7 +983,7 @@ def run_cache_daemon(
     )
     watcher: threading.Thread | None = None
     try:
-        service = _CacheService(metadata)
+        service = _CacheService(metadata, defer_context=True)
         _write_metadata(metadata)
         watcher = threading.Thread(
             target=_watch_workspace,
@@ -900,10 +995,7 @@ def run_cache_daemon(
         service.start_prewarm()
         while (
             not service.shutdown.is_set()
-            and (
-                service.cache_state == "warming"
-                or time.monotonic() - service.last_activity < idle_timeout
-            )
+            and time.monotonic() - service.last_activity < idle_timeout
         ):
             try:
                 connection, _ = listener.accept()
@@ -915,10 +1007,10 @@ def run_cache_daemon(
     finally:
         if "service" in locals():
             service.shutdown.set()
-        if watcher is not None:
-            watcher.join(timeout=2.0)
         listener.close()
         _remove_metadata_if_owned(metadata)
+        if watcher is not None:
+            watcher.join(timeout=2.0)
 
 
 def _start_cache_unlocked(
@@ -972,6 +1064,8 @@ def _start_cache_unlocked(
         process = subprocess.Popen(command, **options)
         deadline = time.monotonic() + startup_timeout
         startup_ready = False
+        timed_out = False
+        return_code: int | None = None
         try:
             while time.monotonic() < deadline:
                 metadata = _read_metadata(canonical)
@@ -985,10 +1079,12 @@ def _start_cache_unlocked(
                 if process.poll() is not None:
                     break
                 time.sleep(0.05)
-            if process.poll() is None:
+            return_code = process.poll()
+            timed_out = return_code is None
+            if timed_out:
                 process.kill()
             with contextlib.suppress(Exception):
-                process.wait()
+                return_code = process.wait()
             metadata = _read_metadata(canonical)
             if metadata and metadata.pid == process.pid:
                 _remove_metadata_if_owned(metadata)
@@ -996,9 +1092,28 @@ def _start_cache_unlocked(
             raw = _read_startup_tail(diagnostics)
             message = _truncate_and_sanitize_startup_diagnostics(raw)
             base = "Cache daemon did not become ready."
+            if timed_out:
+                reason = (
+                    f" Startup timed out after {startup_timeout:.1f}s before "
+                    "readiness metadata was published."
+                )
+            else:
+                reason = (
+                    f" Child process exited with code {return_code} before "
+                    "readiness metadata was published."
+                )
             if message:
-                raise CacheClientError("startup_failed", f"{base} {message}")
-            raise CacheClientError("startup_failed", base)
+                raise CacheClientError(
+                    "startup_failed",
+                    f"{base}{reason} Child stderr: {message}",
+                )
+            raise CacheClientError(
+                "startup_failed",
+                (
+                    f"{base}{reason} No child diagnostics were emitted. "
+                    f"Python executable: {sys.executable}. Workspace: {canonical}."
+                ),
+            )
         finally:
             if not startup_ready:
                 if process.poll() is None:
@@ -1022,15 +1137,16 @@ def start_cache(
         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):
-        return _start_cache_unlocked(
-            root,
-            project_file=project_file,
-            max_memory_bytes=max_memory_bytes,
-            workers=workers,
-            idle_timeout=idle_timeout,
-            startup_timeout=startup_timeout,
-        )
+    with _process_start_lock(root):
+        with _start_lock(root, startup_timeout):
+            return _start_cache_unlocked(
+                root,
+                project_file=project_file,
+                max_memory_bytes=max_memory_bytes,
+                workers=workers,
+                idle_timeout=idle_timeout,
+                startup_timeout=startup_timeout,
+            )
 
 
 def query_cache(root: str | Path, request: dict[str, object]) -> CacheClientResponse:

delphi_lsp/agent_cli.py

@@ -24,8 +24,17 @@ from .agent_cache import (
     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_protocol import (
+    SCHEMA_VERSION,
+    AgentProtocolError,
+    SUPPORTED_ACTIONS,
+    SUPPORTED_DETAILS,
+    SUPPORTED_DIRECTIONS,
+    SUPPORTED_GRAPHS,
+    SUPPORTED_RELATIONS,
+)
 from .agent_templates import install_opencode_support, install_skill
+from .agent_wiki import WikiExportError, export_okf_wiki
 from .parallel_outline import ParallelOutlineError, parse_worker_setting
 
 
@@ -84,6 +93,19 @@ def build_parser() -> argparse.ArgumentParser:
     index.add_argument("--workers", type=parse_worker_setting, default=0)
     index.set_defaults(func=_index)
 
+    wiki = subcommands.add_parser("wiki", help="Export a portable Markdown knowledge wiki.")
+    wiki_commands = wiki.add_subparsers(dest="wiki_command", required=True)
+    wiki_export = wiki_commands.add_parser(
+        "export",
+        help="Export all indexed codebase knowledge as an Open Knowledge Format bundle.",
+    )
+    wiki_export.add_argument("--root", type=Path, default=Path("."))
+    wiki_export.add_argument("--project-file", type=Path)
+    wiki_export.add_argument("--out", type=Path, default=Path(".delphi-lsp") / "wiki")
+    wiki_export.add_argument("--workers", type=parse_worker_setting, default=0)
+    wiki_export.add_argument("--force", action="store_true")
+    wiki_export.set_defaults(func=_wiki_export)
+
     skill = subcommands.add_parser("skill", help="Install agent skill templates.")
     skill_commands = skill.add_subparsers(dest="skill_command", required=True)
     skill_install = skill_commands.add_parser("install", help="Install .agents skill.")
@@ -108,13 +130,13 @@ def build_parser() -> argparse.ArgumentParser:
     )
     opencode_install.set_defaults(func=_opencode_install)
 
-    worker = subcommands.add_parser("worker", help="Serve Protocol v2 NDJSON requests.")
+    worker = subcommands.add_parser("worker", help="Serve Protocol v3 NDJSON requests.")
     worker.add_argument("--root", type=Path, required=True)
     worker.add_argument("--project-file", type=Path)
     worker.add_argument("--workers", type=parse_worker_setting, default=0)
     worker.set_defaults(func=_worker)
 
-    cache = subcommands.add_parser("cache", help="Manage the shared Protocol v2 cache daemon.")
+    cache = subcommands.add_parser("cache", help="Manage the shared Protocol v3 cache daemon.")
     cache_commands = cache.add_subparsers(dest="cache_command", required=True)
     cache_start = cache_commands.add_parser("start", help="Start the cache daemon if needed.")
     _add_cache_start_arguments(cache_start)
@@ -141,6 +163,9 @@ def build_parser() -> argparse.ArgumentParser:
     query.add_argument("--project-id", default="")
     query.add_argument("--detail", choices=SUPPORTED_DETAILS, default="summary")
     query.add_argument("--relation", choices=SUPPORTED_RELATIONS)
+    query.add_argument("--graph", choices=SUPPORTED_GRAPHS, default="full")
+    query.add_argument("--direction", choices=SUPPORTED_DIRECTIONS, default="out")
+    query.add_argument("--depth", type=_cpg_depth, default=4)
     query.add_argument("--cursor", default="")
     query.add_argument("--max-items", type=_max_items, default=12)
     query.add_argument("--max-chars", type=_max_chars, default=12000)
@@ -179,6 +204,13 @@ def _positive_integer(value: str) -> int:
     return parsed
 
 
+def _cpg_depth(value: str) -> int:
+    parsed = int(value)
+    if not 1 <= parsed <= 16:
+        raise argparse.ArgumentTypeError("depth must be between 1 and 16")
+    return parsed
+
+
 def _max_items(value: str) -> int:
     parsed = int(value)
     if not 1 <= parsed <= 50:
@@ -270,7 +302,26 @@ def _index(args: argparse.Namespace) -> None:
     print(args.out)
 
 
+def _wiki_export(args: argparse.Namespace) -> None:
+    args.root = _workspace_root(args.root)
+    output = args.out
+    if not output.is_absolute():
+        output = args.root / output
+    try:
+        result = export_okf_wiki(
+            args.root,
+            output,
+            project_file=args.project_file,
+            workers=args.workers,
+            force=args.force,
+        )
+    except WikiExportError as error:
+        raise _CliError("wiki_export_failed", str(error)) from None
+    _write_json(result.to_mapping())
+
+
 def _skill_install(args: argparse.Namespace) -> None:
+    _require_install_directory(args.target)
     try:
         skill_path = install_skill(args.target, force=args.force)
     except FileExistsError as error:
@@ -279,6 +330,7 @@ def _skill_install(args: argparse.Namespace) -> None:
 
 
 def _opencode_install(args: argparse.Namespace) -> None:
+    _require_install_directory(args.target)
     try:
         skill_path, plugin_path, agent_path = install_opencode_support(
             args.target,
@@ -293,6 +345,12 @@ def _opencode_install(args: argparse.Namespace) -> None:
     print(agent_path)
 
 
+def _require_install_directory(target: str | Path) -> None:
+    path = Path(target).expanduser()
+    if path.exists() and not path.is_dir():
+        raise _CliError("io_error", f"Install target is not a directory: {path}")
+
+
 def _worker(args: argparse.Namespace) -> None:
     args.root = _workspace_root(args.root)
     context = _open_worker_context(args.root, args.project_file, args.workers)
@@ -430,13 +488,23 @@ def _query(args: argparse.Namespace) -> int:
     if args.value:
         if args.action in {"find", "metrics"}:
             request["query"] = args.value
-        elif args.action in {"focus", "inspect", "trace"}:
+        elif args.action in {"focus", "inspect", "trace", "cpg"}:
             request["target_id"] = args.value
         else:
             sys.stderr.write(f"cache_error:invalid_request: {args.action} does not accept a value.\n")
             sys.stderr.flush()
             return 1
-    for argument, field in (("project_id", "project_id"), ("detail", "detail"), ("relation", "relation"), ("cursor", "cursor"), ("max_items", "max_items"), ("max_chars", "max_chars")):
+    for argument, field in (
+        ("project_id", "project_id"),
+        ("detail", "detail"),
+        ("relation", "relation"),
+        ("graph", "graph"),
+        ("direction", "direction"),
+        ("depth", "depth"),
+        ("cursor", "cursor"),
+        ("max_items", "max_items"),
+        ("max_chars", "max_chars"),
+    ):
         value = getattr(args, argument)
         if value is not None:
             request[field] = value
@@ -521,7 +589,7 @@ def _serve_worker(context: AgentContext, input_stream: BinaryIO, output_stream:
             message = _worker_error("internal_error", _INTERNAL_ERROR_MESSAGE)
         _write_worker_message(output_stream, message)
 def _worker_error(code: str, message: str) -> dict[str, object]:
-    return {"schema": 2, "error": {"code": code, "message": message}}
+    return {"schema": SCHEMA_VERSION, "error": {"code": code, "message": message}}
 
 
 def _write_worker_message(output_stream: BinaryIO, message: object) -> None: