plugin-scanner 2.0.689__tar.gz → 2.0.691__tar.gz

{plugin_scanner-2.0.689 → plugin_scanner-2.0.691}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.689
+Version: 2.0.691
 Summary: Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows.
 Project-URL: Homepage, https://github.com/hashgraph-online/hol-guard
 Project-URL: Repository, https://github.com/hashgraph-online/hol-guard

{plugin_scanner-2.0.689 → plugin_scanner-2.0.691}/dashboard/src/guard-types.ts

@@ -593,6 +593,7 @@ export type GuardHarnessActionErrorPayload = {
   harness?: string;
   confirmation_phrase?: string;
   confirm_command?: string;
+  retryable?: boolean;
 };
 
 export type GuardInventoryItem = {

{plugin_scanner-2.0.689 → plugin_scanner-2.0.691}/dashboard/src/harness-action-errors.test.ts

@@ -3,6 +3,7 @@ import {
   isApprovalGateRequiredError,
   isGuardHarnessActionError,
   isSupplyChainSyncConnectError,
+  isSupplyChainSyncRetryableError,
   readHarnessActionUserMessage,
   resolveApprovalGateSyncFailure,
 } from "./harness-action-errors";
@@ -141,6 +142,26 @@ assert(
   "sync transport failures are not connect errors",
 );
 
+assert(
+  isSupplyChainSyncRetryableError(
+    makeHarnessError(503, {
+      error: "supply_chain_sync_unavailable",
+      message: "Guard Cloud is unavailable. Local Guard keeps protecting this machine.",
+      retryable: true,
+    }),
+  ),
+  "retryable cloud outage sync errors are detected",
+);
+assert(
+  !isSupplyChainSyncRetryableError(
+    makeHarnessError(503, {
+      error: "supply_chain_sync_unavailable",
+      message: "Supply-chain sync is not available on this device.",
+    }),
+  ),
+  "non-retryable sync unavailable errors are not retryable",
+);
+
 const networkFailure = resolveApprovalGateSyncFailure(new Error("Failed to fetch"), {
   hasCredentials: true,
 });

{plugin_scanner-2.0.689 → plugin_scanner-2.0.691}/dashboard/src/harness-action-errors.ts

@@ -77,6 +77,16 @@ export function isSupplyChainSyncConnectError(error: unknown): boolean {
   return code !== null && SUPPLY_CHAIN_CONNECT_ERROR_CODES.has(code);
 }
 
+export function isSupplyChainSyncRetryableError(error: unknown): boolean {
+  if (!isGuardHarnessActionError(error)) {
+    return false;
+  }
+  if (readHarnessActionErrorCode(error) !== "supply_chain_sync_unavailable") {
+    return false;
+  }
+  return error.payload?.retryable === true;
+}
+
 export function readHarnessActionUserMessage(error: unknown, fallback: string): string {
   if (error instanceof Error && GUARD_FETCH_NETWORK_ERROR_MESSAGE.test(error.message)) {
     return "Guard lost connection while syncing supply-chain intel. Confirm the local daemon is still running, then try again.";

{plugin_scanner-2.0.689 → plugin_scanner-2.0.691}/dashboard/src/supply-chain-firewall-panel.tsx

@@ -19,6 +19,7 @@ import {
 import {
   isApprovalGateRequiredError,
   isSupplyChainSyncConnectError,
+  isSupplyChainSyncRetryableError,
   readHarnessActionUserMessage,
   resolveApprovalGateSyncFailure,
 } from "./harness-action-errors";
@@ -382,6 +383,16 @@ export const PackageFirewallPanel = forwardRef(function PackageFirewallPanel(
             return;
           }
         }
+        if (isSupplyChainSyncRetryableError(err)) {
+          const message = readHarnessActionUserMessage(
+            err,
+            "Guard Cloud is temporarily unavailable. Try syncing again in a few minutes.",
+          );
+          setAuditRecoveryError(message);
+          setAuditRecoveryPhase("ready");
+          setLastFailed({ op: "sync", manager: null, message });
+          return;
+        }
         const failure = resolveApprovalGateSyncFailure(err, {
           hasCredentials: credentials !== undefined,
         });
@@ -599,6 +610,16 @@ export const PackageFirewallPanel = forwardRef(function PackageFirewallPanel(
             return;
           }
         }
+        if (isSupplyChainSyncRetryableError(err)) {
+          const message = readHarnessActionUserMessage(
+            err,
+            "Guard Cloud is temporarily unavailable. Try syncing again in a few minutes.",
+          );
+          setAuditRecoveryPhase("ready");
+          setAuditRecoveryError(message);
+          setLastFailed({ op, manager: null, message });
+          return;
+        }
         const message = readHarnessActionUserMessage(err, "Operation failed.");
         setLastFailed({ op, manager: null, message });
       } finally {

{plugin_scanner-2.0.689 → plugin_scanner-2.0.691}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plugin-scanner"
-version = "2.0.689"
+version = "2.0.691"
 description = "Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.689 → plugin_scanner-2.0.691}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.689"
+version = "2.0.691"
 description = "Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, and OpenCode."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.689 → plugin_scanner-2.0.691}/src/codex_plugin_scanner/guard/daemon/server.py

@@ -302,14 +302,14 @@ def _supply_chain_package_action_error_response(
             },
         )
     if isinstance(error, GuardSyncNotAvailableError):
-        return (
-            503,
-            {
-                "error": "supply_chain_sync_unavailable",
-                "message": str(error).strip() or "Supply-chain sync is not available on this device.",
-                "operation": operation,
-            },
-        )
+        payload: dict[str, object] = {
+            "error": "supply_chain_sync_unavailable",
+            "message": str(error).strip() or "Supply-chain sync is not available on this device.",
+            "operation": operation,
+        }
+        if error.retryable:
+            payload["retryable"] = True
+        return (503, payload)
     message = str(error).strip() or "Guard supply-chain bundle sync failed."
     return (
         502,

{plugin_scanner-2.0.689 → plugin_scanner-2.0.691}/src/codex_plugin_scanner/guard/local_supply_chain.py

@@ -54,6 +54,11 @@ from .runtime.supply_chain_package_eval import (
     evaluate_package_request_artifact,
 )
 from .runtime.supply_chain_support import ecosystem_support_matrix
+from .runtime.workspace_path_guard import (
+    read_bytes_within_workspace,
+    read_text_within_workspace,
+    resolve_path_within_workspace,
+)
 from .shims import package_shim_status, package_shim_supported_managers
 from .stable_digest import stable_digest_hex
 from .store import GuardStore
@@ -363,11 +368,7 @@ def _is_audit_sensitive_basename(name: str) -> bool:
 def _read_workspace_audit_text(workspace_dir: Path, relative_path: str) -> str | None:
     if _is_audit_sensitive_basename(Path(relative_path).name):
         return None
-    disk_path = workspace_dir / relative_path
-    try:
-        return disk_path.read_text(encoding="utf-8")
-    except (OSError, UnicodeDecodeError):
-        return None
+    return read_text_within_workspace(workspace_dir, relative_path)
 
 
 def _workspace_has_project_markers(workspace_dir: Path) -> bool:
@@ -1961,20 +1962,16 @@ def _workspace_audit_lockfile_context(
 ) -> dict[str, object] | None:
     if not lockfile_paths:
         return None
-    lockfile_path = workspace_dir / lockfile_paths[0]
-    if not lockfile_path.exists():
+    lockfile_path = resolve_path_within_workspace(workspace_dir, lockfile_paths[0])
+    if lockfile_path is None or not lockfile_path.exists():
         return None
     lockfile_text = _read_workspace_audit_text(workspace_dir, lockfile_paths[0])
     if lockfile_text is None:
         return None
     manifest_hash = None
     if manifest_paths:
-        manifest_path = workspace_dir / manifest_paths[0]
-        try:
-            manifest_bytes = manifest_path.read_bytes()
-        except OSError:
-            manifest_bytes = None
-        if manifest_bytes is not None and not _is_audit_sensitive_basename(manifest_path.name):
+        manifest_bytes = read_bytes_within_workspace(workspace_dir, manifest_paths[0])
+        if manifest_bytes is not None and not _is_audit_sensitive_basename(Path(manifest_paths[0]).name):
             manifest_hash = stable_digest_hex(manifest_bytes)
     return {
         "dependencyCount": len(inventory),
@@ -2012,13 +2009,10 @@ def _workspace_audit_fingerprint(
 def _hash_existing_paths(workspace_dir: Path, relative_paths: Sequence[str]) -> list[str]:
     hashes: list[str] = []
     for relative_path in relative_paths:
-        disk_path = workspace_dir / relative_path
-        if not disk_path.exists():
-            continue
-        try:
-            hashes.append(stable_digest_hex(disk_path.read_bytes()))
-        except OSError:
+        payload = read_bytes_within_workspace(workspace_dir, relative_path)
+        if payload is None:
             continue
+        hashes.append(stable_digest_hex(payload))
     return hashes
 
 

{plugin_scanner-2.0.689 → plugin_scanner-2.0.691}/src/codex_plugin_scanner/guard/runtime/manifest_dependency_targets.py

@@ -6,6 +6,7 @@ from pathlib import Path
 
 from ..models import GuardArtifact
 from .package_manifest_diff import parse_manifest_dependencies
+from .workspace_path_guard import read_text_within_workspace, resolve_path_within_workspace
 
 _MANIFEST_ECOSYSTEMS = {
     "package.json": "npm",
@@ -67,12 +68,11 @@ def unsynced_manifest_dependency_targets(
         for relative_path in lockfile_paths:
             if not isinstance(relative_path, str) or not relative_path:
                 continue
-            lockfile_path = workspace_dir / relative_path
-            if not lockfile_path.exists():
+            lockfile_path = resolve_path_within_workspace(workspace_dir, relative_path)
+            if lockfile_path is None or not lockfile_path.exists():
                 continue
-            try:
-                lockfile_text = lockfile_path.read_text(encoding="utf-8")
-            except (OSError, UnicodeDecodeError):
+            lockfile_text = read_text_within_workspace(workspace_dir, relative_path)
+            if lockfile_text is None:
                 continue
             lockfile_ecosystem = _lockfile_ecosystem(lockfile_path.name) or "npm"
             for package_name in parse_manifest_dependencies(path=relative_path, text=lockfile_text):
@@ -84,12 +84,11 @@ def unsynced_manifest_dependency_targets(
         ecosystem = _manifest_ecosystem_for_path(relative_path)
         if ecosystem is None:
             continue
-        manifest_path = workspace_dir / relative_path
-        if not manifest_path.exists():
+        manifest_path = resolve_path_within_workspace(workspace_dir, relative_path)
+        if manifest_path is None or not manifest_path.exists():
             continue
-        try:
-            manifest_text = manifest_path.read_text(encoding="utf-8")
-        except (OSError, UnicodeDecodeError):
+        manifest_text = read_text_within_workspace(workspace_dir, relative_path)
+        if manifest_text is None:
             continue
         dependency_map = _artifact_manifest_dependency_map(
             package_manager=package_manager,

{plugin_scanner-2.0.689 → plugin_scanner-2.0.691}/src/codex_plugin_scanner/guard/runtime/package_intent_common.py

@@ -12,6 +12,7 @@ from typing import Literal
 
 from ..models import GuardArtifact
 from .mcp_protection import _split_package_token
+from .workspace_path_guard import existing_paths_within_workspace
 
 IntentKind = Literal["install", "execute", "sync"]
 _EXTRAS_RE = re.compile(r"^(?P<name>[A-Za-z0-9_.-]+)\[(?P<extras>[A-Za-z0-9_,.-]+)\]$")
@@ -176,19 +177,7 @@ def flag_tokens(tokens: tuple[str, ...]) -> tuple[str, ...]:
 
 
 def existing_relative_paths(workspace: Path | None, candidates: tuple[str, ...] | list[str]) -> tuple[str, ...]:
-    if workspace is None:
-        return ()
-    resolved: list[str] = []
-    for candidate in candidates:
-        if not candidate:
-            continue
-        path = Path(candidate)
-        disk_path = path if path.is_absolute() else workspace / path
-        if disk_path.exists():
-            normalized = candidate if not path.is_absolute() else path.name
-            if normalized not in resolved:
-                resolved.append(normalized)
-    return tuple(resolved)
+    return existing_paths_within_workspace(workspace, candidates)
 
 
 def first_positional(tokens: tuple[str, ...], *, skip_value_options: set[str]) -> str | None:

{plugin_scanner-2.0.689 → plugin_scanner-2.0.691}/src/codex_plugin_scanner/guard/runtime/runner.py

@@ -261,7 +261,13 @@ class GuardSyncNotConfiguredError(RuntimeError):
 
 
 class GuardSyncNotAvailableError(RuntimeError):
-    """Raised when the sync endpoint returns 403 (free-plan restriction)."""
+    """Raised when Guard Cloud sync is blocked by plan limits or temporary outages."""
+
+    retryable: bool
+
+    def __init__(self, message: str, *, retryable: bool = False) -> None:
+        super().__init__(message)
+        self.retryable = retryable
 
 
 class GuardSyncAuthorizationExpiredError(GuardSyncNotConfiguredError):
@@ -1427,6 +1433,35 @@ def sync_receipts(
     return summary
 
 
+def _guard_cloud_http_error_details(error: urllib.error.HTTPError) -> tuple[str, bool]:
+    try:
+        raw_body = error.read().decode("utf-8", errors="replace")
+    except OSError:
+        raw_body = ""
+    retryable = error.code in {503, 524}
+    payload: object = None
+    if raw_body:
+        try:
+            payload = json.loads(raw_body)
+        except json.JSONDecodeError:
+            payload = None
+    message: str | None = None
+    if isinstance(payload, dict):
+        message = _read_guard_cloud_error_message(payload)
+        guard_error = payload.get("guardError")
+        if isinstance(guard_error, dict):
+            if guard_error.get("retryable") is True:
+                retryable = True
+            guard_code = guard_error.get("code")
+            unavailable_codes = {"guard_unavailable", "guard_cloud_unavailable"}
+            if isinstance(guard_code, str) and guard_code.strip().lower() in unavailable_codes:
+                retryable = True
+    if message is None:
+        normalized_body = raw_body.strip()
+        message = normalized_body or f"HTTP Error {error.code}: {error.reason}"
+    return message, retryable
+
+
 def _fetch_supply_chain_bundle_payload(request: urllib.request.Request) -> dict[str, object]:
     try:
         return _urlopen_json_with_timeout_retry(
@@ -1440,7 +1475,10 @@ def _fetch_supply_chain_bundle_payload(request: urllib.request.Request) -> dict[
             if is_plan_restricted:
                 raise GuardSyncNotAvailableError(message) from error
             raise RuntimeError(message) from error
-        raise RuntimeError(_sync_http_error_message(error)) from error
+        message, retryable = _guard_cloud_http_error_details(error)
+        if retryable:
+            raise GuardSyncNotAvailableError(message, retryable=True) from error
+        raise RuntimeError(message) from error
     except OSError as error:
         raise RuntimeError(_sync_url_error_message(error)) from error
 

{plugin_scanner-2.0.689 → plugin_scanner-2.0.691}/src/codex_plugin_scanner/guard/runtime/supply_chain_package_eval.py

@@ -60,6 +60,11 @@ from .supply_chain_bundle_models import (
 )
 from .supply_chain_bundle_runtime import _is_high_confidence_block
 from .supply_chain_support import ecosystem_support_metadata
+from .workspace_path_guard import (
+    read_bytes_within_workspace,
+    read_text_within_workspace,
+    resolve_path_within_workspace,
+)
 
 _DECISION_RANK = {"allow": 0, "monitor": 1, "warn": 2, "ask": 3, "block": 4}
 _SEVERITY_RANK = {"unknown": 0, "low": 1, "medium": 2, "high": 3, "critical": 4}
@@ -1392,12 +1397,11 @@ def _lockfile_context(workspace_dir: Path | None, artifact: GuardArtifact) -> di
     lockfile_paths = artifact.metadata.get("lockfile_paths")
     if not isinstance(lockfile_paths, list) or not lockfile_paths:
         return None
-    lockfile_path = workspace_dir / str(lockfile_paths[0])
-    if not lockfile_path.exists():
+    lockfile_path = resolve_path_within_workspace(workspace_dir, str(lockfile_paths[0]))
+    if lockfile_path is None or not lockfile_path.exists():
         return None
-    try:
-        lockfile_text = lockfile_path.read_text(encoding="utf-8")
-    except (OSError, UnicodeDecodeError):
+    lockfile_text = read_text_within_workspace(workspace_dir, str(lockfile_paths[0]))
+    if lockfile_text is None:
         return None
     dependencies = _safe_dependency_map_for_path(
         str(lockfile_path.name), lockfile_text, deadline=time.monotonic() + _LOCKFILE_PARSE_BUDGET_SECONDS
@@ -1436,8 +1440,8 @@ def _transitive_lockfile_results(
         direct_target_names_by_ecosystem.setdefault(ecosystem, set()).update(candidate_names)
         all_direct_target_names.update(candidate_names)
     for relative_path in lockfile_paths:
-        lockfile_path = workspace_dir / str(relative_path)
-        if not lockfile_path.exists():
+        lockfile_path = resolve_path_within_workspace(workspace_dir, str(relative_path))
+        if lockfile_path is None or not lockfile_path.exists():
             continue
         lockfile_ecosystem = _lockfile_ecosystem(lockfile_path.name)
         direct_target_names = (
@@ -1445,9 +1449,8 @@ def _transitive_lockfile_results(
             if lockfile_ecosystem is not None
             else all_direct_target_names
         )
-        try:
-            lockfile_text = lockfile_path.read_text(encoding="utf-8")
-        except (OSError, UnicodeDecodeError):
+        lockfile_text = read_text_within_workspace(workspace_dir, str(relative_path))
+        if lockfile_text is None:
             continue
         dependency_entries: list[tuple[str, str, str, bool]] = []
         parse_deadline = time.monotonic() + _LOCKFILE_PARSE_BUDGET_SECONDS
@@ -1835,9 +1838,11 @@ def _bun_lockfile_binary_fallback_packages(
         return []
     bun_lock_path = next(
         (
-            workspace_dir / str(relative_path)
+            resolved
             for relative_path in lockfile_paths
-            if Path(str(relative_path)).name == "bun.lockb" and (workspace_dir / str(relative_path)).exists()
+            if Path(str(relative_path)).name == "bun.lockb"
+            and (resolved := resolve_path_within_workspace(workspace_dir, str(relative_path))) is not None
+            and resolved.exists()
         ),
         None,
     )
@@ -2170,12 +2175,20 @@ def _go_replace_result(
     manifest_paths = artifact.metadata.get("manifest_paths")
     if not isinstance(manifest_paths, list):
         return None
-    go_mod_path = next((workspace_dir / str(path) for path in manifest_paths if Path(str(path)).name == "go.mod"), None)
-    if go_mod_path is None or not go_mod_path.exists():
+    go_mod_relative_path = next(
+        (
+            str(path)
+            for path in manifest_paths
+            if Path(str(path)).name == "go.mod"
+            and (resolved := resolve_path_within_workspace(workspace_dir, str(path))) is not None
+            and resolved.exists()
+        ),
+        None,
+    )
+    if go_mod_relative_path is None:
         return None
-    try:
-        go_mod_text = go_mod_path.read_text(encoding="utf-8")
-    except (OSError, UnicodeDecodeError):
+    go_mod_text = read_text_within_workspace(workspace_dir, go_mod_relative_path)
+    if go_mod_text is None:
         return None
     replacements = _go_mod_replace_map(go_mod_text)
     for candidate in _target_candidate_names(target):
@@ -2442,12 +2455,11 @@ def _lockfile_dependency_versions(
         ecosystem="pypi",
     )
     for relative_path in lockfile_paths:
-        lockfile_path = workspace_dir / str(relative_path)
-        if not lockfile_path.exists():
+        lockfile_path = resolve_path_within_workspace(workspace_dir, str(relative_path))
+        if lockfile_path is None or not lockfile_path.exists():
             continue
-        try:
-            lockfile_text = lockfile_path.read_text(encoding="utf-8")
-        except (OSError, UnicodeDecodeError):
+        lockfile_text = read_text_within_workspace(workspace_dir, str(relative_path))
+        if lockfile_text is None:
             continue
         if lockfile_path.name == "package-lock.json":
             versions.update(_package_lock_target_versions(lockfile_text, targets))
@@ -2498,12 +2510,11 @@ def _manifest_direct_dependency_names(
     package_manager = str(artifact.metadata.get("package_manager") or "npm")
     direct_names: set[str] = set()
     for relative_path in manifest_paths:
-        manifest_path = workspace_dir / str(relative_path)
-        if not manifest_path.exists():
+        manifest_path = resolve_path_within_workspace(workspace_dir, str(relative_path))
+        if manifest_path is None or not manifest_path.exists():
             continue
-        try:
-            manifest_text = manifest_path.read_text(encoding="utf-8")
-        except (OSError, UnicodeDecodeError):
+        manifest_text = read_text_within_workspace(workspace_dir, str(relative_path))
+        if manifest_text is None:
             continue
         dependency_map = _artifact_manifest_dependency_map(
             package_manager=package_manager,
@@ -2529,12 +2540,11 @@ def _manifest_dependency_versions(
     keyed_targets = {target_key: target for target in targets if (target_key := _lockfile_target_key(target))}
     versions: dict[tuple[str, str | None], str] = {}
     for relative_path in manifest_paths:
-        manifest_path = workspace_dir / str(relative_path)
-        if not manifest_path.exists():
+        manifest_path = resolve_path_within_workspace(workspace_dir, str(relative_path))
+        if manifest_path is None or not manifest_path.exists():
             continue
-        try:
-            manifest_text = manifest_path.read_text(encoding="utf-8")
-        except (OSError, UnicodeDecodeError):
+        manifest_text = read_text_within_workspace(workspace_dir, str(relative_path))
+        if manifest_text is None:
             continue
         dependency_map = _artifact_manifest_dependency_map(
             package_manager=package_manager,
@@ -3277,15 +3287,14 @@ def _lockfile_parse_warning_result(
         return None
     target_ecosystem = _optional_string(target.get("ecosystem")) or "npm"
     for relative_path in lockfile_paths:
-        lockfile_path = workspace_dir / str(relative_path)
-        if not lockfile_path.exists():
+        lockfile_path = resolve_path_within_workspace(workspace_dir, str(relative_path))
+        if lockfile_path is None or not lockfile_path.exists():
             continue
         lockfile_ecosystem = _lockfile_ecosystem(lockfile_path.name)
         if lockfile_ecosystem is not None and lockfile_ecosystem != target_ecosystem:
             continue
-        try:
-            lockfile_text = lockfile_path.read_text(encoding="utf-8")
-        except (OSError, UnicodeDecodeError):
+        lockfile_text = read_text_within_workspace(workspace_dir, str(relative_path))
+        if lockfile_text is None:
             continue
         _dependency_map, error = _safe_dependency_map_result_for_path(
             lockfile_path.name,
@@ -3472,13 +3481,10 @@ def _hash_paths(workspace_dir: Path | None, raw_paths: object) -> list[str]:
         return []
     hashes: list[str] = []
     for item in raw_paths:
-        path = workspace_dir / str(item)
-        if not path.exists():
-            continue
-        try:
-            hashes.append(stable_digest_hex(path.read_bytes()))
-        except OSError:
+        payload = read_bytes_within_workspace(workspace_dir, str(item))
+        if payload is None:
             continue
+        hashes.append(stable_digest_hex(payload))
     return hashes
 
 

plugin_scanner-2.0.691/src/codex_plugin_scanner/guard/runtime/workspace_path_guard.py

@@ -0,0 +1,67 @@
+"""Contain workspace-relative manifest and lockfile reads."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def resolve_path_within_workspace(workspace_dir: Path, relative_path: str) -> Path | None:
+    """Resolve a workspace-relative path and ensure it remains inside the workspace."""
+
+    if not relative_path:
+        return None
+    candidate = Path(relative_path)
+    if candidate.is_absolute():
+        return None
+    workspace_root = workspace_dir.expanduser().resolve()
+    try:
+        resolved = (workspace_root / candidate).resolve()
+        resolved.relative_to(workspace_root)
+    except (OSError, ValueError):
+        return None
+    return resolved
+
+
+def read_text_within_workspace(workspace_dir: Path, relative_path: str) -> str | None:
+    resolved = resolve_path_within_workspace(workspace_dir, relative_path)
+    if resolved is None or not resolved.is_file():
+        return None
+    try:
+        return resolved.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
+def read_bytes_within_workspace(workspace_dir: Path, relative_path: str) -> bytes | None:
+    resolved = resolve_path_within_workspace(workspace_dir, relative_path)
+    if resolved is None or not resolved.is_file():
+        return None
+    try:
+        return resolved.read_bytes()
+    except OSError:
+        return None
+
+
+def existing_paths_within_workspace(
+    workspace: Path | None,
+    candidates: tuple[str, ...] | list[str],
+) -> tuple[str, ...]:
+    """Return workspace-contained relative paths that exist on disk."""
+
+    if workspace is None:
+        return ()
+    workspace_root = workspace.expanduser().resolve()
+    resolved_paths: list[str] = []
+    for candidate in candidates:
+        if not candidate:
+            continue
+        disk_path = resolve_path_within_workspace(workspace_root, candidate)
+        if disk_path is None or not disk_path.exists():
+            continue
+        try:
+            normalized = disk_path.relative_to(workspace_root).as_posix()
+        except ValueError:
+            continue
+        if normalized not in resolved_paths:
+            resolved_paths.append(normalized)
+    return tuple(resolved_paths)

{plugin_scanner-2.0.689 → plugin_scanner-2.0.691}/src/codex_plugin_scanner/version.py

@@ -1,3 +1,3 @@
 """Single source of truth for tool version."""
 
-__version__ = "2.0.689"
+__version__ = "2.0.691"