Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
from __future__ import annotations
import atexit
import asyncio
import contextlib
import errno
import fnmatch
import hashlib
import importlib.resources as package_resources
import json
import logging
import os
import random
import re
import shlex
import shutil
import signal
import stat
import subprocess
import tarfile
import tempfile
import threading
import time
import urllib.parse
import urllib.request
import weakref
from dataclasses import dataclass, replace
from enum import Enum
from pathlib import Path
from typing import IO, Any, Callable, Iterable, Iterator, Mapping
from uuid import uuid4
import httpx
from storage.lock import (
MigrationFileLock,
MigrationLockTimeout,
_try_lock as storage_lock_try_lock,
fcntl_available,
try_windows_exclusive_lock,
unlock_windows_exclusive_lock,
)
from config import paths
from config.atomic_io import write_atomic
from core.dependency_network import dependency_error_details, fetch_to_path, probe_url, redact_url
from core.managed_runtime import (
ManagedRuntimeArchive,
ManagedRuntimeManager,
ManagedRuntimeManifest,
ManagedRuntimeSpec,
env_flag_enabled,
file_sha256,
runtime_platform_tag,
safe_extract_tar,
safe_path_part,
)
from core.process_isolation import KILL_SIGNAL, isolated_subprocess_kwargs, signal_process_tree
from core.show_runtime_failures import (
ShowRuntimeFailureClass,
ShowRuntimeFailureDimension,
ShowRuntimeFailureEvidence,
ShowRuntimeRecoveryAction,
classify_show_runtime_failure,
show_runtime_recovery_action,
)
from core.show_runtime_source import retired_show_runtime_source
logger = logging.getLogger(__name__)
_RUNTIME_BIN = "avibe-show-runtime"
_RUNTIME_PACKAGE = "@avibe/show-runtime"
_RUNTIME_ARCHIVE_PREFIX = "vibe-show-runtime-node"
_RUNTIME_ARCHIVE_RELEASE_BASE_URL = "https://github.com/avibe-bot/vibe-show-runtime/releases/latest/download"
_RUNTIME_SOURCE_MANIFEST = "manifest-cache"
_RUNTIME_SOURCE_ARCHIVE = "archive"
_RUNTIME_SOURCE_NPM = "npm"
_WARNED_RETIRED_RUNTIME_SOURCES: set[str] = set()
_RUNTIME_MANIFEST_RESOURCE = "show_runtime_manifest.json"
_PACKAGED_RUNTIME_MANIFEST_SOURCE = f"package:{_RUNTIME_MANIFEST_RESOURCE}"
_CONTENT_ADDRESSED_ARCHIVE_RE = re.compile(r"^[0-9a-f]{64}\.tgz$")
_ABANDONED_ARCHIVE_CLAIM_RE = re.compile(r"^[0-9a-f]{64}\.tgz\.avibe-removing$")
# Cross-process safety window: between a download finalizing ``<sha256>.tgz``
# and the installing process writing install metadata / ``current.json``, the
# archive is not yet protected. Archives younger than this window are never
# pruned by automatic or manual cleanup; real stale archives are days old.
_ARCHIVE_MTIME_GUARD_SECONDS = 15 * 60
# Skip reasons for archive-cache cleanup; consumers (CLI, Doctor) key off
# ``skipped_reason`` generically instead of matching literal strings.
_SKIPPED_ARCHIVE_REASON_INSTALL_RUNNING = "runtime_install_already_running"
_SKIPPED_ARCHIVE_REASON_INSPECTION_FAILED = "archive_inspection_failed"
_SKIPPED_ARCHIVE_REASON_REMOVAL_FAILED = "archive_removal_failed"
# Every archive-cache report carries exactly one outcome from this set; the
# enumeration test in tests/test_show_runtime_archive_cleanup.py pins CLI and
# Doctor rendering to it, so a new outcome fails the test until wired.
_ARCHIVE_CLEANUP_OUTCOMES = frozenset({"cleaned", "partial", "skipped"})
_INSTALL_REFERENCE_RE = re.compile(r"^[0-9a-f]{32}\.lock$")
_INSTALL_REFERENCE_LOCKS: dict[tuple[str, str], "_ShowRuntimeInstallReference"] = {}
# Allocations inside the guard can collect a manager and run its finalizer
# synchronously on the same thread.
_INSTALL_REFERENCE_LOCKS_GUARD = threading.RLock()
class _ArchiveMetadataError(Exception):
"""A retained install's metadata could not be read; destructive cleanup must abort."""
class _ArchiveInspectionError(Exception):
"""The archive cache itself could not be inspected; cleanup must abort."""
@dataclass
class _ShowRuntimeInstallReference:
marker: Path
handle: IO[str]
owners: set[str]
def _unlock_install_reference(handle: IO[str]) -> None:
try:
if os.name == "nt":
handle.seek(0)
unlock_windows_exclusive_lock(handle.fileno())
else:
import fcntl
fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
finally:
handle.close()
def _release_install_reference_owner(owner: str) -> None:
released: list[_ShowRuntimeInstallReference] = []
with _INSTALL_REFERENCE_LOCKS_GUARD:
for key, reference in list(_INSTALL_REFERENCE_LOCKS.items()):
reference.owners.discard(owner)
if reference.owners:
continue
released.append(reference)
_INSTALL_REFERENCE_LOCKS.pop(key, None)
for reference in released:
try:
_unlock_install_reference(reference.handle)
finally:
reference.marker.unlink(missing_ok=True)
def _is_exclusive_regular_file(info: os.stat_result) -> bool:
"""True only for a one-link regular file that is not a reparse point."""
if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1:
return False
attrs = getattr(info, "st_file_attributes", 0)
reparse = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0)
return not (reparse and attrs & reparse)
def _is_reparse_point(info: os.stat_result) -> bool:
if stat.S_ISLNK(info.st_mode):
return True
attrs = getattr(info, "st_file_attributes", 0)
reparse = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0)
return bool(reparse and attrs & reparse)
_FALSE_VALUES = {"0", "false", "no", "off"}
_PREWARM_IMPORT_RE = re.compile(r"""(?P<quote>["'])(?P<path>[^"']+)(?P=quote)""")
_PREWARM_MAX_ASSETS = 64
_PREWARM_MAX_DEPTH = 4
SHOW_RUNTIME_PROTOCOL_VERSION = 1
SHOW_RUNTIME_PROTOCOL_HEADER = "X-Avibe-Show-Protocol"
SHOW_RUNTIME_CONTEXT_HEADER = "X-Avibe-Show-Context"
SHOW_RUNTIME_BASE_HEADER = "x-vibe-show-base"
SHOW_RUNTIME_TARGET_HEADER = "x-vibe-show-target"
SHOW_RUNTIME_CONTEXT_KEY_FEATURE = "show-context-key-v1"
SHOW_RUNTIME_RENDER_MARKDOWN_CAPABILITY = "render_markdown_ssr"
# Phase 2.1 measured ~2 s cold against a 10 s Runtime module-load budget; this margin has no browser-install allowance.
SHOW_RUNTIME_REQUEST_TIMEOUT_SECONDS = 30.0
_CAPABILITY_RETRY_BASE_SECONDS = 0.25
_CAPABILITY_RETRY_MAX_SECONDS = 5.0
_CAPABILITY_RETRYABLE_STATUS_CODES = {408, 429}
_CAPABILITY_ENDPOINT_UNSUPPORTED = object()
SHOW_RUNTIME_CLI_FALLBACK_DELAY_SECONDS = 30
_STARTUP_READY_TIMEOUT_SECONDS = 10.0
_STARTUP_POLL_INTERVAL_SECONDS = 0.05
_STARTUP_URL_TIMEOUT_REASON = "runtime_start_url_timeout"
_STARTUP_PROCESS_UNAVAILABLE_REASON = "runtime_start_process_unavailable"
_STARTUP_HEALTH_TIMEOUT_REASON = "runtime_start_health_timeout"
_STARTUP_COMMAND_UNAVAILABLE_REASON = "runtime_start_command_unavailable"
_STARTUP_COMMAND_INVALID_REASON = "runtime_start_command_invalid"
_STARTUP_ATTEMPT_FAILED_REASON = "runtime_start_attempt_failed"
_MISSING = object()
class ShowRuntimeStartabilityState(str, Enum):
STARTABLE = "startable"
NOT_STARTABLE = "not_startable"
UNDETERMINED = "undetermined"
@dataclass(frozen=True)
class ShowRuntimeStartability:
state: ShowRuntimeStartabilityState
reason: str | None = None
detail: str | None = None
def __post_init__(self) -> None:
if self.state is ShowRuntimeStartabilityState.STARTABLE and (self.reason or self.detail):
raise ValueError("startable outcome cannot carry failure evidence")
if self.state is ShowRuntimeStartabilityState.NOT_STARTABLE and (
not self.reason or self.detail
):
raise ValueError("not-startable outcome requires only a reason")
if self.state is ShowRuntimeStartabilityState.UNDETERMINED and (
self.reason or not self.detail
):
raise ValueError("undetermined outcome requires only a detail")
@classmethod
def startable(cls) -> "ShowRuntimeStartability":
return cls(ShowRuntimeStartabilityState.STARTABLE)
@classmethod
def not_startable(cls, reason: str) -> "ShowRuntimeStartability":
return cls(ShowRuntimeStartabilityState.NOT_STARTABLE, reason=reason)
@classmethod
def undetermined(cls, detail: str) -> "ShowRuntimeStartability":
return cls(ShowRuntimeStartabilityState.UNDETERMINED, detail=detail)
def as_payload(self) -> dict[str, str | None]:
return {
"state": self.state.value,
"reason": self.reason,
"detail": self.detail,
}
class ShowRuntimeContext(str, Enum):
PRIVATE = "private"
SHARED = "shared"
class ShowRuntimeContextCapability(str, Enum):
SUPPORTED = "supported"
UNSUPPORTED = "unsupported"
TRANSIENT_UNKNOWN = "transient-unknown"
@dataclass(frozen=True)
class ShowRuntimeProtocolEnvelope:
context: ShowRuntimeContext
def __post_init__(self) -> None:
if not isinstance(self.context, ShowRuntimeContext):
raise TypeError("Show Runtime protocol 1 requires an explicit private or shared context")
def headers(self, forwarded: Mapping[str, str] | None = None) -> dict[str, str]:
blocked = {SHOW_RUNTIME_PROTOCOL_HEADER.lower(), SHOW_RUNTIME_CONTEXT_HEADER.lower()}
headers = {
key: value
for key, value in (forwarded or {}).items()
if key.lower() not in blocked
}
headers[SHOW_RUNTIME_PROTOCOL_HEADER] = str(SHOW_RUNTIME_PROTOCOL_VERSION)
headers[SHOW_RUNTIME_CONTEXT_HEADER] = self.context.value
return headers
@dataclass(frozen=True)
class ShowRuntimeWebSocketTarget:
url: str
headers: dict[str, str]
_base_url: str | None = None
_process: subprocess.Popen[str] | None = None
@dataclass(frozen=True)
class ShowRuntimeResult:
available: bool
base_url: str | None = None
reason: str | None = None
class ShowRuntimeRequestTimeoutError(TimeoutError):
"""A proxied Runtime request exceeded its total request deadline."""
class ShowRuntimeResponseLimitError(ValueError):
"""A handler response violates this request's bounded transport policy."""
class ShowRuntimeUnavailableError(RuntimeError):
def __init__(
self,
reason: str,
failure_class: ShowRuntimeFailureClass,
recovery_action: ShowRuntimeRecoveryAction,
):
self.reason = reason
self.failure_class = failure_class
self.recovery_action = recovery_action
super().__init__(reason)
class ShowRuntimePolicyState(str, Enum):
ALLOWED = "allowed"
SKIPPED = "skipped"
class ShowRuntimeInstallState(str, Enum):
INSTALLED = "installed"
ABSENT = "absent"
FAILED = "failed"
class ShowRuntimeServingState(str, Enum):
SERVING = "serving"
UNCHECKED = "unchecked"
START_FAILED = "start_failed"
class _ShowRuntimeOperationState(str, Enum):
COMPLETED = "completed"
FAILED = "failed"
NOT_APPLICABLE = "not_applicable"
@dataclass(frozen=True)
class _ShowRuntimeOperationOutcome:
state: _ShowRuntimeOperationState
reason: str | None
def __post_init__(self) -> None:
if self.state is _ShowRuntimeOperationState.COMPLETED and self.reason:
raise ValueError("completed operation cannot carry a failure reason")
if self.state is not _ShowRuntimeOperationState.COMPLETED and not self.reason:
raise ValueError("incomplete operation requires a reason")
@property
def ok(self) -> bool:
return self.state is _ShowRuntimeOperationState.COMPLETED
@dataclass(frozen=True)
class _ManagedInstallAttempt:
command: list[str] | None
operation_reason: str | None = None
def __post_init__(self) -> None:
if self.command and self.operation_reason:
raise ValueError("successful install attempt cannot carry an operation failure")
if not self.command and not self.operation_reason:
raise ValueError("failed install attempt requires an operation reason")
@dataclass(frozen=True)
class _ShowRuntimeDiskInstall:
install_dir: Path
command: list[str] | None
metadata: Mapping[str, Any]
@dataclass(frozen=True)
class ShowRuntimeAvailability:
policy: ShowRuntimePolicyState = ShowRuntimePolicyState.ALLOWED
install: ShowRuntimeInstallState = ShowRuntimeInstallState.ABSENT
runtime: ShowRuntimeServingState = ShowRuntimeServingState.UNCHECKED
command: list[str] | None = None
base_url: str | None = None
policy_reason: str | None = None
policy_failure_class: ShowRuntimeFailureClass | None = None
policy_recovery_action: ShowRuntimeRecoveryAction | None = None
install_reason: str | None = None
install_failure_class: ShowRuntimeFailureClass | None = None
install_recovery_action: ShowRuntimeRecoveryAction | None = None
install_dir: str | None = None
install_runtime_version: str | None = None
install_matches_manifest: bool | None = None
runtime_reason: str | None = None
runtime_failure_class: ShowRuntimeFailureClass | None = None
runtime_recovery_action: ShowRuntimeRecoveryAction | None = None
def __post_init__(self) -> None:
for dimension, reason, failure_class, recovery_action in (
(
"policy",
self.policy_reason,
self.policy_failure_class,
self.policy_recovery_action,
),
(
"install",
self.install_reason,
self.install_failure_class,
self.install_recovery_action,
),
(
"runtime",
self.runtime_reason,
self.runtime_failure_class,
self.runtime_recovery_action,
),
):
evidence = (failure_class, recovery_action)
if reason is None and any(value is not None for value in evidence):
raise ValueError(f"{dimension} recovery evidence requires a reason")
if reason is not None and any(value is None for value in evidence):
raise ValueError(f"{dimension} reason requires complete recovery evidence")
@property
def ok(self) -> bool:
return self.install is ShowRuntimeInstallState.INSTALLED
@property
def available(self) -> bool:
return self.runtime is ShowRuntimeServingState.SERVING and self.base_url is not None
@property
def reason(self) -> str | None:
return self.runtime_reason or self.install_reason or self.policy_reason
@property
def failure_class(self) -> ShowRuntimeFailureClass | None:
return self.runtime_failure_class or self.install_failure_class or self.policy_failure_class
@property
def recovery_action(self) -> ShowRuntimeRecoveryAction | None:
return self.runtime_recovery_action or self.install_recovery_action or self.policy_recovery_action
@classmethod
def from_install(
cls,
*,
command: list[str] | None = None,
install: ShowRuntimeInstallState | None = None,
policy_reason: str | None = None,
install_reason: str | None = None,
install_evidence: ShowRuntimeFailureEvidence | None = None,
install_failure_class: ShowRuntimeFailureClass | None = None,
install_recovery_action: ShowRuntimeRecoveryAction | None = None,
install_dir: Path | str | None = None,
install_runtime_version: str | None = None,
install_matches_manifest: bool | None = None,
) -> "ShowRuntimeAvailability":
if install is None:
if command:
install = ShowRuntimeInstallState.INSTALLED
elif install_reason:
install = ShowRuntimeInstallState.FAILED
else:
install = ShowRuntimeInstallState.ABSENT
policy_evidence = ShowRuntimeFailureEvidence(
ShowRuntimeFailureDimension.POLICY,
policy_reason,
)
if install_evidence is None:
install_evidence = ShowRuntimeFailureEvidence(
ShowRuntimeFailureDimension.INSTALL,
install_reason,
)
elif (
install_evidence.dimension is not ShowRuntimeFailureDimension.INSTALL
or install_evidence.reason != install_reason
):
raise ValueError("install evidence must describe the published install reason")
resolved_install_failure_class = install_failure_class or (
classify_show_runtime_failure(install_evidence) if install is ShowRuntimeInstallState.FAILED else None
)
return cls(
policy=(ShowRuntimePolicyState.SKIPPED if policy_reason else ShowRuntimePolicyState.ALLOWED),
install=install,
command=command,
policy_reason=policy_reason,
policy_failure_class=(classify_show_runtime_failure(policy_evidence) if policy_reason else None),
policy_recovery_action=(show_runtime_recovery_action(policy_evidence) if policy_reason else None),
install_reason=install_reason,
install_failure_class=resolved_install_failure_class,
install_recovery_action=(
install_recovery_action or (show_runtime_recovery_action(install_evidence) if install_reason else None)
),
install_dir=str(install_dir) if install_dir is not None else None,
install_runtime_version=install_runtime_version,
install_matches_manifest=install_matches_manifest,
)
def as_payload(self) -> dict[str, Any]:
command = list(self.command) if self.command else None
return {
"policy": {
"state": self.policy.value,
"reason": self.policy_reason,
"failure_class": self.policy_failure_class.value if self.policy_failure_class else None,
"recovery_action": self.policy_recovery_action.value if self.policy_recovery_action else None,
},
"install": {
"state": self.install.value,
"reason": self.install_reason,
"failure_class": self.install_failure_class.value if self.install_failure_class else None,
"recovery_action": self.install_recovery_action.value if self.install_recovery_action else None,
"command": command,
"install_dir": self.install_dir,
"runtime_version": self.install_runtime_version,
"matches_manifest": self.install_matches_manifest,
},
"runtime": {
"state": self.runtime.value,
"reason": self.runtime_reason,
"failure_class": self.runtime_failure_class.value if self.runtime_failure_class else None,
"recovery_action": self.runtime_recovery_action.value if self.runtime_recovery_action else None,
"base_url": self.base_url,
},
# Compatibility fields remain projections of the three dimensions.
"ok": self.ok,
"command": command,
"reason": self.reason,
}
_SHOW_MANAGED_RUNTIME_SPEC = ManagedRuntimeSpec(
runtime_id="runtime",
manifest_resource=_RUNTIME_MANIFEST_RESOURCE,
version_field="runtime_version",
default_bin_path="node_modules/@avibe/show-runtime/dist/cli.js",
binary_artifact=False,
record_provider=_RUNTIME_SOURCE_MANIFEST,
metadata_filename_override=".vibe-show-runtime.json",
allow_legacy_missing_runtime_id=True,
staging_prefixes=("install-", "manifest-"),
)
class _ShowManifestRuntimeManager(ManagedRuntimeManager):
"""Show policy and released-record declarations over the shared installer."""
def __init__(self, owner: "ShowRuntimeManager", *, offline: bool) -> None:
self.owner = owner
super().__init__(
spec=_SHOW_MANAGED_RUNTIME_SPEC,
runtime_dir=owner.runtime_dir,
manifest_path=owner.manifest_path,
manifest_url=owner.manifest_url,
offline=offline,
)
def load_manifest(self, *, allow_network: bool) -> ManagedRuntimeManifest | None:
return self._load_manifest(allow_network=allow_network)
def archive_for_platform(
self,
manifest: ManagedRuntimeManifest,
) -> ManagedRuntimeArchive | None:
return self._manifest_archive_for_platform(manifest)
def verified_entrypoint(
self,
install_dir: Path,
manifest: ManagedRuntimeManifest,
archive: ManagedRuntimeArchive,
) -> Path | None:
admitted = self._verified_manifest_binary(install_dir, manifest, archive)
return self._project_entrypoint(install_dir) if admitted is not None else None
def installed_result_entrypoint(self, result: Mapping[str, Any]) -> Path | None:
if not result.get("ok") or not isinstance(result.get("path"), str):
return None
install_dir = result.get("install_dir")
if not isinstance(install_dir, str):
return None
entrypoint = self._project_entrypoint(Path(install_dir))
return entrypoint if entrypoint.is_file() else None
def resolve_selected_entrypoint(self) -> Path | None:
manifest = self._load_manifest(allow_network=False)
if manifest is None or not self._manifest_installable(manifest):
return None
archive = self._manifest_archive_for_platform(manifest)
if archive is None:
return None
for install_dir in self._manifest_install_candidates(manifest, archive):
entrypoint = self._verified_manifest_binary(install_dir, manifest, archive)
if entrypoint is not None:
return self._project_entrypoint(install_dir)
return None
def _project_entrypoint(self, install_dir: Path) -> Path:
return install_dir / self.spec.default_bin_path
def install_candidates(
self,
manifest: ManagedRuntimeManifest,
archive: ManagedRuntimeArchive,
) -> Iterator[Path]:
return self._manifest_install_candidates(manifest, archive)
def _manifest_installable(self, manifest: ManagedRuntimeManifest) -> bool:
node = _resolve_node_command()
if node is None:
self._install_reason = "runtime_node_missing"
return False
minimum_node = self._minimum_node(manifest)
if minimum_node and not _node_satisfies_requirement(_node_version(node), minimum_node):
self._install_reason = "runtime_node_unsupported"
return False
return True
def _parse_manifest(
self,
payload: bytes,
*,
loaded_from: str,
) -> ManagedRuntimeManifest | None:
manifest = super()._parse_manifest(payload, loaded_from=loaded_from)
if manifest is None:
return None
if "minimum_node" in manifest.payload and not isinstance(
manifest.payload["minimum_node"],
str,
):
self._install_reason = "runtime_manifest_invalid"
return None
return manifest
def _manifest_archive_for_platform(
self,
manifest: ManagedRuntimeManifest,
) -> ManagedRuntimeArchive | None:
archive = super()._manifest_archive_for_platform(manifest)
if archive is not None and archive.bin_path != self.spec.default_bin_path:
self._install_reason = "runtime_manifest_invalid"
return None
return archive
def _binary_matches_manifest(
self,
binary: Path,
manifest: ManagedRuntimeManifest,
) -> bool:
del binary, manifest
return True
def _manifest_identity_fields(self, manifest: ManagedRuntimeManifest) -> dict[str, str]:
minimum_node = self._minimum_node(manifest)
return {"minimum_node": minimum_node} if minimum_node else {}
def _metadata_matches_install_target(
self,
metadata: Mapping[str, Any],
target: Mapping[str, str],
) -> bool:
if metadata.get("runtime_id") is None:
target = {key: value for key, value in target.items() if key != "minimum_node"}
return super()._metadata_matches_install_target(metadata, target)
def _manifest_install_candidates(
self,
manifest: ManagedRuntimeManifest,
archive: ManagedRuntimeArchive,
) -> Iterator[Path]:
install_dir = self._manifest_install_dir(manifest, archive)
legacy_parent = install_dir.parent
yield install_dir
yield legacy_parent
try:
candidates = sorted(legacy_parent.iterdir(), key=lambda path: path.name)
except OSError:
return
for candidate in candidates:
if candidate == install_dir:
continue
try:
metadata = json.loads(
(candidate / self.spec.metadata_filename).read_text(encoding="utf-8")
)
except Exception:
continue
manifest_sha256 = metadata.get("manifest_sha256")
if not isinstance(manifest_sha256, str) or not _CONTENT_ADDRESSED_ARCHIVE_RE.fullmatch(
f"{manifest_sha256}.tgz"
):
continue
previous_fingerprint = hashlib.sha256(
f"{manifest_sha256}:{archive.sha256}".encode("utf-8")
).hexdigest()[:16]
if candidate.name == previous_fingerprint:
yield candidate
def _archive_cache_name(self, archive: ManagedRuntimeArchive) -> str:
return f"{archive.sha256}.tgz"
def _install_record_archive_name(
self,
metadata: Mapping[str, Any],
archive_name: str,
archive_sha256: str,
) -> str:
del metadata, archive_name
return f"{archive_sha256}.tgz"
def _read_archive_provenance(self) -> set[tuple[str, str]]:
provenance = super()._read_archive_provenance()
downloads_dir = self.runtime_dir / "downloads"
try:
downloads_info = downloads_dir.lstat()
except FileNotFoundError:
return provenance
except OSError as exc:
raise OSError("downloads directory cannot be inspected") from exc
if _is_reparse_point(downloads_info) or not stat.S_ISDIR(downloads_info.st_mode):
raise OSError("downloads directory is not a confined directory")
try:
with os.scandir(downloads_dir) as entries:
for entry in entries:
match = _CONTENT_ADDRESSED_ARCHIVE_RE.fullmatch(entry.name)
claim = _ABANDONED_ARCHIVE_CLAIM_RE.fullmatch(entry.name)
if match is None and claim is None:
continue
info = entry.stat(follow_symlinks=False)
if not _is_exclusive_regular_file(info):
continue
provenance.add((entry.name, entry.name[:64]))
except OSError as exc:
raise OSError("downloads directory cannot be inspected") from exc
return provenance
def _archive_candidate_sha256(self, name: str, fd: int) -> str:
if _CONTENT_ADDRESSED_ARCHIVE_RE.fullmatch(name) or _ABANDONED_ARCHIVE_CLAIM_RE.fullmatch(name):
return name[:64]
return super()._archive_candidate_sha256(name, fd)
def _clean_downloaded_archives(
self,
*,
archive_provenance: set[tuple[str, str]],
protected_sha256s: set[str],
dry_run: bool,
) -> tuple[dict[str, Any], set[str]]:
report, terminal_names = super()._clean_downloaded_archives(
archive_provenance=archive_provenance,
protected_sha256s=protected_sha256s,
dry_run=dry_run,
)
report["protected_count"] = len(protected_sha256s)
return report, terminal_names
def _record_matches_configured_source(self, metadata: Mapping[str, Any]) -> bool:
source = metadata.get("manifest_source")
configured_source = self.owner._configured_manifest_source()
return source == configured_source or (
isinstance(source, str)
and self.owner.manifest_url is not None
and source == f"cache:{self.owner.manifest_url}"
)
def _record_install_dir_matches(
self,
install_dir: Path,
metadata: Mapping[str, Any],
) -> bool:
runtime_version = metadata.get("runtime_version")
platform_tag = metadata.get("platform")
archive_sha256 = metadata.get("archive_sha256")
manifest_sha256 = metadata.get("manifest_sha256")
if not all(
isinstance(value, str) and value
for value in (runtime_version, platform_tag, archive_sha256, manifest_sha256)
):
return False
if not all(
_CONTENT_ADDRESSED_ARCHIVE_RE.fullmatch(f"{value}.tgz")
for value in (archive_sha256, manifest_sha256)
):
return False
try:
parts = install_dir.relative_to((self.runtime_dir / "versions").resolve()).parts
except (OSError, ValueError):
return False
expected_prefix = (safe_path_part(runtime_version), safe_path_part(platform_tag))
if parts[:2] != expected_prefix:
return False
if len(parts) == 2:
return True
if len(parts) != 3:
return False
current_fingerprint = hashlib.sha256(
f"{runtime_version}:{platform_tag}:{archive_sha256}".encode("utf-8")
).hexdigest()[:16]
previous_fingerprint = hashlib.sha256(
f"{manifest_sha256}:{archive_sha256}".encode("utf-8")
).hexdigest()[:16]
for fingerprint in (current_fingerprint, previous_fingerprint):
if parts[2] == fingerprint:
return True
prefix = f"{fingerprint}-"
suffix = parts[2][len(prefix) :] if parts[2].startswith(prefix) else ""
if len(suffix) == 8 and all(
character.isascii() and (character.isalnum() or character == "_")
for character in suffix
):
return True
return False
def _retention_ranked_installs(self, installs: list[Any], protected: set[Path]) -> list[Any]:
resolved_by_path = {install.path: install.path.resolve() for install in installs}
protected.update(
resolved
for resolved in resolved_by_path.values()
if self.owner._install_dir_has_live_reference(resolved)
)
return [
install
for install in installs
if not any(
resolved_by_path[install.path] in other.parents
for other in resolved_by_path.values()
if other != resolved_by_path[install.path]
)
and not self._install_dir_is_protected(
resolved_by_path[install.path],
protected,
)
]
def _manifest_path_read_error_reason(self) -> str:
return "runtime_manifest_invalid"
def _reason(self, suffix: str) -> str:
aliases = {
"install_lock_failed": "runtime_install_guard_unavailable",
"install_missing_binary": "runtime_install_missing_bin",
}
return aliases.get(suffix, f"runtime_{suffix}")
@staticmethod
def _minimum_node(manifest: ManagedRuntimeManifest) -> str | None:
value = manifest.payload.get("minimum_node")
return value if isinstance(value, str) and value else None
class ShowRuntimeManager:
def __init__(
self,
*,
command: str | None = None,
workspace_root: Path | None = None,
runtime_dir: Path | None = None,
auto_install: bool | None = None,
package_spec: str | None = None,
runtime_source: str | None = None,
archive_path: Path | str | None = None,
archive_url: str | None = None,
manifest_path: Path | str | None = None,
manifest_url: str | None = None,
offline: bool | None = None,
force_install: bool = False,
) -> None:
configured_command = command or os.environ.get("VIBE_SHOW_RUNTIME_BIN")
self.command = configured_command or _RUNTIME_BIN
self._command_explicit = configured_command is not None
self.workspace_root = workspace_root or paths.get_show_pages_dir()
self.runtime_dir = runtime_dir or paths.get_runtime_dir() / "show-runtime"
archive_path_value = archive_path or os.environ.get("VIBE_SHOW_RUNTIME_ARCHIVE_PATH")
self.archive_path = Path(archive_path_value).expanduser() if archive_path_value else None
archive_url_env = os.environ.get("VIBE_SHOW_RUNTIME_ARCHIVE_URL")
manifest_path_value = manifest_path or os.environ.get("VIBE_SHOW_RUNTIME_MANIFEST_PATH")
self.manifest_path = Path(manifest_path_value).expanduser() if manifest_path_value else None
self.manifest_url = manifest_url if manifest_url is not None else os.environ.get("VIBE_SHOW_RUNTIME_MANIFEST_URL")
source_value = runtime_source or os.environ.get("VIBE_SHOW_RUNTIME_SOURCE")
if source_value is None and (archive_path_value or archive_url is not None or archive_url_env):
source_value = _RUNTIME_SOURCE_ARCHIVE
self.auto_install = _auto_install_enabled() if auto_install is None else auto_install
self.package_spec = package_spec or os.environ.get("VIBE_SHOW_RUNTIME_PACKAGE_SPEC") or _RUNTIME_PACKAGE
self.runtime_source = _normalize_runtime_source(source_value)
configured_archive_url = archive_url if archive_url is not None else archive_url_env
self.archive_url = configured_archive_url if configured_archive_url is not None else _default_runtime_archive_url()
self._archive_url_provenance = "configured" if configured_archive_url is not None else "packaged"
self.offline = env_flag_enabled("VIBE_SHOW_RUNTIME_OFFLINE", default=False) if offline is None else offline
self.force_install = force_install
self.stdout_path = self.runtime_dir / "stdout.log"
self.stderr_path = self.runtime_dir / "stderr.log"
self.install_log_path = self.runtime_dir / "install.log"
self.cache_root = self.runtime_dir / "vite-cache"
self._install_evidence: ShowRuntimeFailureEvidence | None = None
self._download_error: dict[str, Any] | None = None
self._managed_command: list[str] | None = None
self._availability = ShowRuntimeAvailability()
self._process: subprocess.Popen[str] | None = None
self._base_url: str | None = None
self._lock = asyncio.Lock()
self._capability_lock = asyncio.Lock()
# Cross-process in-flight install guard for the archive cache: held for
# the whole resolve-download-validate-extract window so a concurrent
# ``runtime clean`` (or another process's post-install cleanup) cannot
# unlink an archive this process has validated but not yet opened.
# ``flock`` is not re-entrant across file handles, so the depth counter
# lets the post-install cleanup reuse the installer's lock.
self._install_guard = threading.RLock()
self._install_guard_depth = 0
self._install_guard_path = self.runtime_dir / ".install.lock"
self._capability_identity: tuple[str, int | None] | None = None
self._context_key_capability: ShowRuntimeContextCapability | None = None
self._render_markdown_capability: bool | None = None
self._render_markdown_retry_deadline = 0.0
self._render_markdown_retry_attempt = 0
self._capability_retry_deadline = 0.0
self._capability_retry_attempt = 0
self._capability_generation = 0
self._install_reference_owner = uuid4().hex
self._install_reference_finalizer = weakref.finalize(
self,
_release_install_reference_owner,
self._install_reference_owner,
)
@property
def _install_reason(self) -> str | None:
return self._install_evidence.reason if self._install_evidence else None
@_install_reason.setter
def _install_reason(self, reason: str | None) -> None:
self._install_evidence = (
ShowRuntimeFailureEvidence(ShowRuntimeFailureDimension.INSTALL, reason)
if reason
else None
)
def _record_install_failure(
self,
reason: str,
*,
provenance: str | None = None,
retryable: bool | None = None,
) -> None:
self._install_evidence = ShowRuntimeFailureEvidence(
ShowRuntimeFailureDimension.INSTALL,
reason,
provenance,
retryable,
)
def _record_download_failure(
self,
reason: str,
exc: BaseException,
url: str,
*,
provenance: str,
) -> None:
self._download_error = _runtime_download_error(exc, url)
retryable = self._download_error.get("retryable")
self._record_install_failure(
reason,
provenance=provenance,
retryable=retryable if isinstance(retryable, bool) else None,
)
def _resolve_explicit_command_availability(self) -> ShowRuntimeAvailability:
"""Resolve the configured command without discarding failure evidence."""
if not self._command_explicit:
raise AssertionError("explicit command resolution requires an explicit command")
try:
command = _resolve_command(self.command)
except (OSError, ValueError):
evidence = ShowRuntimeFailureEvidence(
ShowRuntimeFailureDimension.RUNTIME,
_STARTUP_COMMAND_INVALID_REASON,
)
return ShowRuntimeAvailability(
runtime=ShowRuntimeServingState.START_FAILED,
runtime_reason=evidence.reason,
runtime_failure_class=classify_show_runtime_failure(evidence),
runtime_recovery_action=show_runtime_recovery_action(evidence),
)
return ShowRuntimeAvailability.from_install(
command=command,
install_reason=None if command else "runtime_command_missing",
)
def _publish_explicit_command_availability(
self,
availability: ShowRuntimeAvailability,
) -> ShowRuntimeAvailability:
self._availability = availability
return availability
async def ensure(self, *, automatic: bool = True) -> ShowRuntimeAvailability:
async with self._lock:
return await self._admit_runtime_start(automatic=automatic)
async def _admit_runtime_start(self, *, automatic: bool) -> ShowRuntimeAvailability:
"""Own one start admission through readiness publication."""
availability: ShowRuntimeAvailability | None = None
operation: _ShowRuntimeOperationOutcome | None = None
base_url: str | None = None
pending_exception: BaseException | None = None
start_phase = "admission"
try:
availability = self._availability
operation = _ShowRuntimeOperationOutcome(
_ShowRuntimeOperationState.NOT_APPLICABLE,
availability.reason or "runtime_unavailable",
)
if self._base_url:
base_url = self._base_url
operation = _ShowRuntimeOperationOutcome(
_ShowRuntimeOperationState.COMPLETED,
None,
)
else:
self.stop()
command: list[str] | None = None
if self._command_explicit:
start_phase = "resolve-command"
availability = self._publish_explicit_command_availability(
self._resolve_explicit_command_availability()
)
command = availability.command
if availability.runtime_reason:
operation = _ShowRuntimeOperationOutcome(
_ShowRuntimeOperationState.FAILED,
availability.runtime_reason,
)
else:
start_phase = "install"
availability = await self._resolve_managed_availability(automatic=automatic)
command = availability.command
if command:
start_phase = "establish"
self.runtime_dir.mkdir(parents=True, exist_ok=True)
self.workspace_root.mkdir(parents=True, exist_ok=True)
self.cache_root.mkdir(parents=True, exist_ok=True)
# Reap any orphaned runtime server still bound to this workspace root before
# spawning ours, so there is a single writer (avibe#813). self.stop() above
# already released our own tracked child; anything left is a stray from a
# prior avibe instance that died without reaping it (SIGKILL / crash). Run it
# off the event loop: the psutil scan + terminate/kill can block for seconds.
await asyncio.to_thread(self._sweep_orphan_runtime_servers)
with (
self.stdout_path.open(
"w",
encoding="utf-8",
) as stdout,
self.stderr_path.open("w", encoding="utf-8") as stderr,
):
startup_deadline = asyncio.get_running_loop().time() + _STARTUP_READY_TIMEOUT_SECONDS
start_phase = "spawn"
self._process = subprocess.Popen(
[
*command,
"--workspace-root",
str(self.workspace_root),
"--cache-root",
str(self.cache_root),
"--host",
"127.0.0.1",
"--port",
"0",
"--fallback-delay-seconds",
str(SHOW_RUNTIME_CLI_FALLBACK_DELAY_SECONDS),
],
stdout=stdout,
stderr=stderr,
text=True,
**isolated_subprocess_kwargs(),
)
start_phase = "readiness"
base_url = await self._read_startup_url(deadline=startup_deadline)
process = self._process
if process is None or process.poll() is not None:
operation = _ShowRuntimeOperationOutcome(
_ShowRuntimeOperationState.FAILED,
_STARTUP_PROCESS_UNAVAILABLE_REASON,
)
elif not base_url:
operation = _ShowRuntimeOperationOutcome(
_ShowRuntimeOperationState.FAILED,
_STARTUP_URL_TIMEOUT_REASON,
)
elif reason := await self._wait_for_startup_health(
base_url,
process,
deadline=startup_deadline,
):
operation = _ShowRuntimeOperationOutcome(
_ShowRuntimeOperationState.FAILED,
reason,
)
else:
operation = _ShowRuntimeOperationOutcome(
_ShowRuntimeOperationState.COMPLETED,
None,
)
elif operation.state is not _ShowRuntimeOperationState.FAILED:
operation = _ShowRuntimeOperationOutcome(
_ShowRuntimeOperationState.NOT_APPLICABLE,
availability.reason or "runtime_unavailable",
)
except OSError as exc:
reason = _STARTUP_ATTEMPT_FAILED_REASON
if start_phase == "spawn" and exc.errno in {
errno.EACCES,
errno.ENOENT,
errno.ENOEXEC,
}:
reason = (
_STARTUP_COMMAND_INVALID_REASON if self._command_explicit else _STARTUP_COMMAND_UNAVAILABLE_REASON
)
operation = _ShowRuntimeOperationOutcome(
_ShowRuntimeOperationState.FAILED,
reason,
)
logger.exception("Show Runtime start admission raised during %s", start_phase)
except BaseException as exc:
pending_exception = exc
finally:
if pending_exception is not None and self._process is not None:
try:
self.stop()
except OSError:
logger.warning("Show Runtime cancellation cleanup failed", exc_info=True)
if availability is None or operation is None:
availability = self._availability
operation = _ShowRuntimeOperationOutcome(
_ShowRuntimeOperationState.NOT_APPLICABLE,
availability.reason or "runtime_unavailable",
)
published = self._complete_runtime_start_admission(
availability,
operation,
base_url=base_url,
)
if pending_exception is not None:
raise pending_exception
return published
async def request(
self,
method: str,
path: str,
*,
envelope: ShowRuntimeProtocolEnvelope,
headers: dict[str, str] | None = None,
body: bytes | None = None,
base_path: str | None = None,
render_target: str | None = None,
timeout_seconds: float | None = None,
automatic: bool = True,
start_if_needed: bool = True,
max_response_bytes: int | None = None,
) -> httpx.Response:
base_url = self._base_url
process = self._process
if base_url is None:
if not start_if_needed:
evidence = ShowRuntimeFailureEvidence(ShowRuntimeFailureDimension.RUNTIME, "runtime_unavailable")
raise ShowRuntimeUnavailableError(
evidence.reason, classify_show_runtime_failure(evidence), show_runtime_recovery_action(evidence)
)
ready = await self.ensure(automatic=automatic)
if not ready.available or not ready.base_url:
raise self._unavailable_error(ready)
base_url = ready.base_url
process = self._process
await self._negotiate_context_key_capability(base_url)
reserved_headers = {
SHOW_RUNTIME_BASE_HEADER.lower(),
SHOW_RUNTIME_TARGET_HEADER.lower(),
}
request_headers = {
key: value
for key, value in envelope.headers(headers).items()
if key.lower() not in reserved_headers
}
if base_path is not None:
if (
not base_path.startswith("/")
or not base_path.endswith("/")
or "\r" in base_path
or "\n" in base_path
):
raise ValueError("Show Runtime base path must be an absolute path ending in '/'")
request_headers[SHOW_RUNTIME_BASE_HEADER] = base_path
elif session_part := _show_runtime_app_session_part(path):
request_headers[SHOW_RUNTIME_BASE_HEADER] = f"/show/{session_part}/"
if render_target is not None:
if not render_target.startswith("/") or "\r" in render_target or "\n" in render_target:
raise ValueError("Show Runtime render target must be an absolute path")
request_headers[SHOW_RUNTIME_TARGET_HEADER] = render_target
phase_timeout_seconds = SHOW_RUNTIME_REQUEST_TIMEOUT_SECONDS if timeout_seconds is None else timeout_seconds
return await self._request_runtime_transport(
method,
base_url,
path,
process=process,
headers=request_headers,
body=body,
phase_timeout_seconds=phase_timeout_seconds,
total_timeout_seconds=timeout_seconds,
max_response_bytes=max_response_bytes,
)
async def request_global(
self,
method: str,
path: str,
*,
headers: dict[str, str] | None = None,
body: bytes | None = None,
) -> httpx.Response:
"""Request a capability-independent Runtime resource without an app context."""
base_url = self._base_url
process = self._process
if base_url is None:
ready = await self.ensure()
if not ready.available or not ready.base_url:
raise self._unavailable_error(ready)
base_url = ready.base_url
process = self._process
blocked = {
SHOW_RUNTIME_PROTOCOL_HEADER.lower(),
SHOW_RUNTIME_CONTEXT_HEADER.lower(),
SHOW_RUNTIME_BASE_HEADER.lower(),
SHOW_RUNTIME_TARGET_HEADER.lower(),
}
forwarded = {key: value for key, value in (headers or {}).items() if key.lower() not in blocked}
return await self._request_runtime_transport(
method,
base_url,
path,
process=process,
headers=forwarded,
body=body,
phase_timeout_seconds=30.0,
)
async def _request_runtime_transport(
self,
method: str,
base_url: str,
path: str,
*,
process: subprocess.Popen[str] | None,
headers: dict[str, str],
body: bytes | None,
phase_timeout_seconds: float,
total_timeout_seconds: float | None = None,
max_response_bytes: int | None = None,
) -> httpx.Response:
"""Own transport failures and publish their recovery evidence."""
try:
async with httpx.AsyncClient(timeout=httpx.Timeout(phase_timeout_seconds, connect=5.0), trust_env=False) as client:
async def bounded_response() -> httpx.Response:
bounded_headers = {**headers, "accept-encoding": "identity"}
async with client.stream(method, f"{base_url}{path}", headers=bounded_headers, content=body) as response:
# Reject compression before iteration: a decoder may allocate
# arbitrarily large output from a single compressed chunk.
if response.headers.get("content-encoding", "identity").lower() != "identity":
raise ShowRuntimeResponseLimitError("Unsupported Show response encoding")
if len(response.headers) > 64 or sum(
len(k) + len(v) for k, v in response.headers.raw
) > 16 * 1024:
raise ShowRuntimeResponseLimitError("Show response headers exceed limit")
length = response.headers.get("content-length")
if length is not None and (
len(length) > 10 or not length.isdecimal() or int(length) > max_response_bytes
):
raise ShowRuntimeResponseLimitError("Show response exceeds limit")
content = bytearray()
async for chunk in response.aiter_raw():
if len(content) + len(chunk) > max_response_bytes:
raise ShowRuntimeResponseLimitError("Show response exceeds limit")
content.extend(chunk)
materialized_headers = [
(k, v) for k, v in response.headers.raw
if k.lower() not in {b"content-length", b"transfer-encoding", b"content-encoding"}
]
return httpx.Response(
response.status_code, headers=materialized_headers, content=bytes(content),
request=response.request,
)
request = (
client.request(method, f"{base_url}{path}", headers=headers, content=body)
if max_response_bytes is None else bounded_response()
)
if total_timeout_seconds is None:
return await request
try:
return await asyncio.wait_for(request, timeout=total_timeout_seconds)
except (asyncio.TimeoutError, httpx.ReadTimeout) as exc:
raise ShowRuntimeRequestTimeoutError(
f"Show Runtime request exceeded {total_timeout_seconds:g} seconds"
) from exc
except (ShowRuntimeRequestTimeoutError, httpx.RequestError) as exc:
await self._invalidate_runtime_snapshot(base_url, process)
if isinstance(exc, ShowRuntimeRequestTimeoutError):
raise
evidence = ShowRuntimeFailureEvidence(
ShowRuntimeFailureDimension.RUNTIME,
"runtime_proxy_failed",
)
raise ShowRuntimeUnavailableError(
"runtime_proxy_failed",
classify_show_runtime_failure(evidence),
show_runtime_recovery_action(evidence),
) from exc
async def prewarm_session(
self,
session_id: str,
*,
context: ShowRuntimeContext,
) -> ShowRuntimeResult:
session_part = urllib.parse.quote(session_id, safe="")
runtime_path = f"/sessions/{session_part}/app/"
base_path = f"/show/{session_part}/"
envelope = ShowRuntimeProtocolEnvelope(context)
try:
response = await self.request("GET", runtime_path, envelope=envelope)
if response.status_code >= 500:
return ShowRuntimeResult(False, reason=f"session_prewarm_failed:{response.status_code}")
result = await self._prewarm_session_module_graph(
session_id,
runtime_path=runtime_path,
envelope=envelope,
seed_responses=[(runtime_path, response)],
base_path=base_path,
)
if not result.available:
return result
return ShowRuntimeResult(True, self._base_url)
except Exception as exc:
return ShowRuntimeResult(False, reason=f"session_prewarm_failed:{exc}")
async def _prewarm_session_module_graph(
self,
session_id: str,
*,
runtime_path: str,
envelope: ShowRuntimeProtocolEnvelope,
seed_responses: list[tuple[str, httpx.Response]],
base_path: str | None,
) -> ShowRuntimeResult:
pending: list[tuple[str, int]] = [(f"{runtime_path}src/main.tsx", 0)]
visited: set[str] = {path for path, _response in seed_responses}
for path, response in seed_responses:
pending.extend(
(import_path, 1)
for import_path in _show_runtime_prewarm_import_paths(
response,
session_id=session_id,
runtime_path=runtime_path,
base_path=base_path,
)
)
while pending and len(visited) < _PREWARM_MAX_ASSETS:
path, depth = pending.pop(0)
if path in visited or depth > _PREWARM_MAX_DEPTH:
continue
visited.add(path)
response = await self.request("GET", path, envelope=envelope)
if response.status_code >= 500:
return ShowRuntimeResult(False, reason=f"session_prewarm_module_failed:{response.status_code}:{path}")
if response.status_code >= 400:
continue
if depth >= _PREWARM_MAX_DEPTH:
continue
for import_path in _show_runtime_prewarm_import_paths(
response,
session_id=session_id,
runtime_path=runtime_path,
base_path=base_path,
):
if import_path not in visited:
pending.append((import_path, depth + 1))
return ShowRuntimeResult(True, self._base_url)
async def websocket_target(
self,
path: str,
*,
envelope: ShowRuntimeProtocolEnvelope,
) -> ShowRuntimeWebSocketTarget:
ready = await self.ensure()
if not ready.available or not ready.base_url:
raise self._unavailable_error(ready)
base_url = ready.base_url
process = self._process
await self._negotiate_context_key_capability(base_url)
url = f"{base_url.replace('http://', 'ws://', 1).replace('https://', 'wss://', 1)}{path}"
return ShowRuntimeWebSocketTarget(
url=url,
headers=envelope.headers(),
_base_url=base_url,
_process=process,
)
async def invalidate_websocket_target(self, target: ShowRuntimeWebSocketTarget) -> None:
if target._base_url is None:
return
await self._invalidate_runtime_snapshot(target._base_url, target._process)
async def _invalidate_runtime_snapshot(
self,
base_url: str,
process: subprocess.Popen[str] | None,
) -> None:
async with self._lock:
if self._base_url == base_url and self._process is process:
self._base_url = None
self._clear_capability_state()
def _unavailable_error(self, availability: ShowRuntimeAvailability) -> ShowRuntimeUnavailableError:
reason = availability.reason
failure_class = availability.failure_class
recovery_action = availability.recovery_action
if reason is None or failure_class is None or recovery_action is None:
raise AssertionError("unavailable Show Runtime must publish complete recovery evidence")
return ShowRuntimeUnavailableError(
reason,
failure_class,
recovery_action,
)
async def context_key_capability(self) -> ShowRuntimeContextCapability:
ready = await self.ensure()
if not ready.available or not ready.base_url:
return ShowRuntimeContextCapability.TRANSIENT_UNKNOWN
return await self._negotiate_context_key_capability(ready.base_url)
async def supports_render_markdown(self, *, automatic: bool = True) -> bool:
"""Return whether this Runtime process implements Markdown rendering."""
ready = await self.ensure(automatic=automatic)
if not ready.available or not ready.base_url:
raise RuntimeError(ready.reason or "show runtime unavailable")
identity = self._runtime_identity(ready.base_url)
async with self._capability_lock:
if identity != self._capability_identity:
self._clear_capability_state(identity=identity)
if self._render_markdown_capability is not None:
return self._render_markdown_capability
if time.monotonic() < self._render_markdown_retry_deadline:
raise RuntimeError("show runtime capability probe temporarily unavailable")
generation = self._capability_generation
outcome = await self._probe_render_markdown_capability(ready.base_url)
if generation != self._capability_generation or identity != self._runtime_identity(ready.base_url):
raise RuntimeError("show runtime changed during capability probe")
if outcome is None:
self._render_markdown_retry_attempt += 1
self._render_markdown_retry_deadline = (
time.monotonic()
+ _show_runtime_capability_retry_delay(self._render_markdown_retry_attempt)
)
raise RuntimeError("show runtime capability probe unavailable")
self._render_markdown_capability = outcome
self._render_markdown_retry_attempt = 0
self._render_markdown_retry_deadline = 0.0
return outcome
async def _negotiate_context_key_capability(
self,
base_url: str,
) -> ShowRuntimeContextCapability:
async with self._capability_lock:
identity = self._runtime_identity(base_url)
if identity != self._capability_identity:
self._clear_capability_state(identity=identity)
if self._context_key_capability in {
ShowRuntimeContextCapability.SUPPORTED,
ShowRuntimeContextCapability.UNSUPPORTED,
}:
return self._context_key_capability
now = time.monotonic()
if (
self._context_key_capability is ShowRuntimeContextCapability.TRANSIENT_UNKNOWN
and now < self._capability_retry_deadline
):
return ShowRuntimeContextCapability.TRANSIENT_UNKNOWN
generation = self._capability_generation
outcome = await self._probe_context_key_capability(base_url)
if generation != self._capability_generation or identity != self._runtime_identity(base_url):
return ShowRuntimeContextCapability.TRANSIENT_UNKNOWN
self._context_key_capability = outcome
if outcome is ShowRuntimeContextCapability.TRANSIENT_UNKNOWN:
self._capability_retry_attempt += 1
self._capability_retry_deadline = time.monotonic() + _show_runtime_capability_retry_delay(
self._capability_retry_attempt
)
else:
self._capability_retry_attempt = 0
self._capability_retry_deadline = 0.0
return outcome
async def _probe_context_key_capability(self, base_url: str) -> ShowRuntimeContextCapability:
payload = await self._probe_capabilities_payload(base_url)
if payload is _CAPABILITY_ENDPOINT_UNSUPPORTED:
return ShowRuntimeContextCapability.UNSUPPORTED
if not isinstance(payload, dict):
return ShowRuntimeContextCapability.TRANSIENT_UNKNOWN
protocol = payload.get("protocol", _MISSING)
features = payload.get("features", _MISSING)
if protocol is not _MISSING and (isinstance(protocol, bool) or not isinstance(protocol, int)):
return ShowRuntimeContextCapability.TRANSIENT_UNKNOWN
if features is not _MISSING and (
not isinstance(features, list) or any(not isinstance(feature, str) for feature in features)
):
return ShowRuntimeContextCapability.TRANSIENT_UNKNOWN
if protocol == SHOW_RUNTIME_PROTOCOL_VERSION and SHOW_RUNTIME_CONTEXT_KEY_FEATURE in (
features if isinstance(features, list) else []
):
return ShowRuntimeContextCapability.SUPPORTED
return ShowRuntimeContextCapability.UNSUPPORTED
async def _probe_capabilities_payload(self, base_url: str) -> dict[str, Any] | object | None:
try:
async with httpx.AsyncClient(timeout=httpx.Timeout(2.0, connect=0.5), trust_env=False) as client:
response = await client.get(f"{base_url}/capabilities")
except (httpx.TimeoutException, httpx.TransportError):
return None
if response.status_code == 404:
return _CAPABILITY_ENDPOINT_UNSUPPORTED
if response.status_code in _CAPABILITY_RETRYABLE_STATUS_CODES or response.status_code >= 500:
return None
if not 200 <= response.status_code < 300:
return None
try:
payload = response.json()
except (UnicodeDecodeError, ValueError):
return None
if not isinstance(payload, dict):
return None
return payload
async def _probe_render_markdown_capability(self, base_url: str) -> bool | None:
payload = await self._probe_capabilities_payload(base_url)
if payload is _CAPABILITY_ENDPOINT_UNSUPPORTED:
return False
if not isinstance(payload, dict):
return None
protocol = payload.get("protocol", _MISSING)
capability = payload.get(SHOW_RUNTIME_RENDER_MARKDOWN_CAPABILITY, _MISSING)
return (
isinstance(protocol, int)
and not isinstance(protocol, bool)
and protocol == SHOW_RUNTIME_PROTOCOL_VERSION
and capability is True
)
def _runtime_identity(self, base_url: str) -> tuple[str, int | None]:
process = self._process
return base_url, getattr(process, "pid", None) if process is not None else None
def _clear_capability_state(self, *, identity: tuple[str, int | None] | None = None) -> None:
self._capability_identity = identity
self._context_key_capability = None
self._render_markdown_capability = None
self._render_markdown_retry_deadline = 0.0
self._render_markdown_retry_attempt = 0
self._capability_retry_deadline = 0.0
self._capability_retry_attempt = 0
self._capability_generation += 1
async def _healthy(self, base_url: str) -> bool:
try:
async with httpx.AsyncClient(timeout=httpx.Timeout(2.0, connect=0.5), trust_env=False) as client:
response = await client.get(f"{base_url}/health")
return response.status_code == 200
except Exception:
return False
async def _read_startup_url(self, *, deadline: float) -> str | None:
loop = asyncio.get_running_loop()
while loop.time() < deadline:
process = self._process
if process is None or process.poll() is not None:
return None
try:
text = self.stdout_path.read_text(encoding="utf-8")
except FileNotFoundError:
text = ""
for line in reversed(text.splitlines()):
marker = "Vibe Show Runtime listening at "
if marker in line:
return line.split(marker, 1)[1].strip()
await asyncio.sleep(min(_STARTUP_POLL_INTERVAL_SECONDS, max(0.0, deadline - loop.time())))
return None
async def _wait_for_startup_health(
self,
base_url: str,
process: subprocess.Popen[str],
*,
deadline: float,
) -> str | None:
loop = asyncio.get_running_loop()
while True:
if process.poll() is not None:
return _STARTUP_PROCESS_UNAVAILABLE_REASON
remaining = deadline - loop.time()
if remaining <= 0:
return _STARTUP_HEALTH_TIMEOUT_REASON
try:
healthy = await asyncio.wait_for(self._healthy(base_url), timeout=remaining)
except asyncio.TimeoutError:
return _STARTUP_HEALTH_TIMEOUT_REASON
if process.poll() is not None:
return _STARTUP_PROCESS_UNAVAILABLE_REASON
if healthy:
return None
remaining = deadline - loop.time()
if remaining <= 0:
return _STARTUP_HEALTH_TIMEOUT_REASON
await asyncio.sleep(min(_STARTUP_POLL_INTERVAL_SECONDS, remaining))
def stop(self) -> None:
process = self._process
self._process = None
self._base_url = None
self._clear_capability_state()
if not process or process.poll() is not None:
return
signal_process_tree(process, signal.SIGTERM, logger, "show runtime")
try:
process.wait(timeout=5)
except subprocess.TimeoutExpired:
signal_process_tree(process, KILL_SIGNAL, logger, "show runtime")
def _sweep_orphan_runtime_servers(self) -> None:
"""Best-effort reap of stray runtime servers bound to our workspace root."""
keep_pid = self._process.pid if self._process else None
try:
sweep_orphan_show_runtime_servers(self.workspace_root, keep_pid=keep_pid)
except Exception: # pragma: no cover - defensive; sweeping must never block spawn
logger.debug("Orphan show runtime sweep skipped", exc_info=True)
async def _resolve_managed_availability(
self,
*,
automatic: bool = True,
) -> ShowRuntimeAvailability:
if self._command_explicit:
return self._publish_explicit_command_availability(
self._resolve_explicit_command_availability()
)
if not self.force_install and self._managed_command:
return self._publish_install_availability(command=self._managed_command)
if (
not self.force_install
and self.runtime_source != _RUNTIME_SOURCE_ARCHIVE
and not (self.runtime_source == _RUNTIME_SOURCE_MANIFEST and self.manifest_url)
):
command = await asyncio.to_thread(
self._safe_installed_managed_runtime_command,
offline=True,
)
if command:
return self._publish_install_availability(command=command)
admission, _operation = await asyncio.to_thread(
self._attempt_managed_install,
force=self.force_install,
offline=self.offline,
automatic=automatic,
)
return admission
async def _resolve_managed_command(self, *, automatic: bool = True) -> list[str] | None:
availability = await self._resolve_managed_availability(automatic=automatic)
return availability.command
def _attempt_managed_install(
self,
*,
force: bool,
offline: bool,
automatic: bool,
candidate_validator: Callable[[list[str]], ShowRuntimeStartability] | None = None,
) -> tuple[ShowRuntimeAvailability, _ShowRuntimeOperationOutcome]:
admission: ShowRuntimeAvailability | None = None
operation: _ShowRuntimeOperationOutcome | None = None
pending_exception: BaseException | None = None
stack: contextlib.ExitStack | None = None
try:
self._install_evidence = None
self._download_error = None
stack = contextlib.ExitStack()
admission = self._availability
operation = _ShowRuntimeOperationOutcome(
_ShowRuntimeOperationState.NOT_APPLICABLE,
admission.reason or "runtime_unavailable",
)
preflight = self._managed_install_preflight(
force=force,
automatic=automatic,
)
if preflight is not None:
admission, operation = preflight
else:
guard = (
contextlib.nullcontext((True, None))
if self.runtime_source == _RUNTIME_SOURCE_MANIFEST
else self._install_guard_locked()
)
acquired, guard_reason = stack.enter_context(guard)
if not acquired:
command = None if force else self._safe_installed_managed_runtime_command(offline=offline)
if command:
admission = self._publish_install_availability(command=command)
operation = _ShowRuntimeOperationOutcome(
_ShowRuntimeOperationState.COMPLETED,
None,
)
else:
reason = guard_reason or "runtime_install_guard_unavailable"
admission = self._publish_install_availability(
install_reason=reason,
)
operation = _ShowRuntimeOperationOutcome(
_ShowRuntimeOperationState.NOT_APPLICABLE,
reason,
)
else:
preflight = self._managed_install_preflight(
force=force,
automatic=automatic,
)
if preflight is not None:
admission, operation = preflight
else:
if candidate_validator is None:
raw_attempt = self._install_managed_runtime_locked(
force=force,
offline=offline,
)
else:
raw_attempt = self._install_managed_runtime_locked(
force=force,
offline=offline,
candidate_validator=candidate_validator,
)
attempt = (
raw_attempt
if isinstance(raw_attempt, _ManagedInstallAttempt)
else _ManagedInstallAttempt(
raw_attempt,
None if raw_attempt else self._install_reason or "runtime_install_failed",
)
)
if attempt.command:
admission = self._publish_install_availability(command=attempt.command)
operation = _ShowRuntimeOperationOutcome(
_ShowRuntimeOperationState.COMPLETED,
None,
)
else:
reason = attempt.operation_reason or "runtime_install_failed"
installed_command = self._safe_installed_managed_runtime_command(offline=True)
admission = (
self._publish_install_availability(command=installed_command)
if installed_command
else self._publish_install_availability(install_reason=reason)
)
operation = _ShowRuntimeOperationOutcome(
(
_ShowRuntimeOperationState.NOT_APPLICABLE
if reason
in {
"runtime_install_already_running",
"runtime_install_guard_unavailable",
}
else _ShowRuntimeOperationState.FAILED
),
reason,
)
except OSError:
reason = self._install_reason or "runtime_install_failed"
installed_command = self._safe_installed_managed_runtime_command(offline=True)
admission = (
self._publish_install_availability(command=installed_command)
if installed_command
else self._publish_install_availability(install_reason=reason)
)
operation = _ShowRuntimeOperationOutcome(
_ShowRuntimeOperationState.FAILED,
reason,
)
logger.exception("Show Runtime install admission raised")
except BaseException as exc:
pending_exception = exc
finally:
if admission is None or operation is None:
admission = self._availability
operation = _ShowRuntimeOperationOutcome(
_ShowRuntimeOperationState.NOT_APPLICABLE,
admission.reason or "runtime_unavailable",
)
if stack is not None:
stack.close()
if pending_exception is not None:
raise pending_exception
return admission, operation
def _managed_install_preflight(
self,
*,
force: bool,
automatic: bool,
) -> tuple[ShowRuntimeAvailability, _ShowRuntimeOperationOutcome] | None:
if self._command_explicit:
availability = self._publish_explicit_command_availability(
self._resolve_explicit_command_availability()
)
command = availability.command
reason = availability.reason
if force:
operation = _ShowRuntimeOperationOutcome(
_ShowRuntimeOperationState.NOT_APPLICABLE,
"VIBE_SHOW_RUNTIME_BIN",
)
elif command:
operation = _ShowRuntimeOperationOutcome(
_ShowRuntimeOperationState.COMPLETED,
None,
)
else:
operation = _ShowRuntimeOperationOutcome(
_ShowRuntimeOperationState.FAILED,
reason or "runtime_command_missing",
)
return availability, operation
skipped_reason = self._managed_install_opt_out_reason(automatic=automatic)
if skipped_reason:
return self._publish_policy_skip(skipped_reason), _ShowRuntimeOperationOutcome(
_ShowRuntimeOperationState.NOT_APPLICABLE,
skipped_reason,
)
if self._managed_command and not force:
availability = self._publish_install_availability(command=self._managed_command)
operation = _ShowRuntimeOperationOutcome(_ShowRuntimeOperationState.COMPLETED, None)
return availability, operation
return None
def _managed_install_opt_out_reason(self, *, automatic: bool) -> str | None:
if automatic and env_flag_enabled(
"VIBE_INSTALL_SKIP_SHOW_RUNTIME",
default=False,
):
return "VIBE_INSTALL_SKIP_SHOW_RUNTIME"
if automatic and not self.auto_install:
return "VIBE_SHOW_RUNTIME_AUTO_INSTALL"
return None
def _complete_runtime_start_admission(
self,
availability: ShowRuntimeAvailability,
operation: _ShowRuntimeOperationOutcome,
*,
base_url: str | None,
) -> ShowRuntimeAvailability:
"""Publish exactly one start outcome before an admission can leave."""
published = availability
if operation.state is _ShowRuntimeOperationState.COMPLETED:
if not base_url:
raise AssertionError("completed Show Runtime start admission requires a base URL")
self._base_url = base_url
published = self._publish_runtime_availability(
ShowRuntimeServingState.SERVING,
base_url,
)
elif operation.state is _ShowRuntimeOperationState.FAILED:
try:
self.stop()
except OSError: # pragma: no cover - process cleanup must not hide the outcome
logger.warning("Show Runtime start cleanup failed", exc_info=True)
published = self._publish_runtime_availability(
ShowRuntimeServingState.START_FAILED,
runtime_reason=operation.reason,
)
return published
def _publish_policy_skip(self, reason: str) -> ShowRuntimeAvailability:
if self._managed_command:
return self._publish_install_availability(command=self._managed_command, policy_reason=reason)
if self.runtime_source == _RUNTIME_SOURCE_MANIFEST:
manager = self._shared_manifest_manager(offline=True)
disk_install = self._shared_manifest_disk_install(manager)
return self._publish_install_availability(
command=disk_install.command if disk_install else None,
install_state=(ShowRuntimeInstallState.INSTALLED if disk_install else ShowRuntimeInstallState.ABSENT),
policy_reason=reason,
)
command = self._safe_installed_managed_runtime_command(offline=True)
return self._publish_install_availability(command=command, policy_reason=reason)
def _publish_install_availability(
self,
*,
command: list[str] | None = None,
install_state: ShowRuntimeInstallState | None = None,
policy_reason: str | None = None,
install_reason: str | None = None,
install_failure_class: ShowRuntimeFailureClass | None = None,
) -> ShowRuntimeAvailability:
install_evidence = (
self._install_evidence
if install_reason is not None and self._install_reason == install_reason
else None
)
if command:
self._managed_command = command
self._install_evidence = None
elif install_reason is not None and install_evidence is None:
self._install_reason = install_reason
install_evidence = self._install_evidence
elif install_reason is None:
self._install_evidence = None
availability = ShowRuntimeAvailability.from_install(
command=command,
install=install_state,
policy_reason=policy_reason,
install_reason=install_reason,
install_evidence=install_evidence,
install_failure_class=install_failure_class,
)
self._availability = availability
return availability
def _publish_runtime_availability(
self,
runtime: ShowRuntimeServingState,
base_url: str | None = None,
*,
runtime_reason: str | None = None,
) -> ShowRuntimeAvailability:
command = self._availability.command or self._managed_command
install = self._availability.install
if command:
install = ShowRuntimeInstallState.INSTALLED
runtime_evidence = ShowRuntimeFailureEvidence(
ShowRuntimeFailureDimension.RUNTIME,
runtime_reason,
provenance="configured" if self._command_explicit else None,
)
runtime_failure_class = classify_show_runtime_failure(runtime_evidence) if runtime_reason else None
availability = replace(
self._availability,
install=install,
command=command,
runtime=runtime,
base_url=base_url,
runtime_reason=runtime_reason,
runtime_failure_class=runtime_failure_class,
runtime_recovery_action=(show_runtime_recovery_action(runtime_evidence) if runtime_reason else None),
)
self._availability = availability
return availability
def _managed_install_operation_command(
self,
command: list[str] | None,
*,
replacement_required: bool,
replacement_completed: bool = False,
) -> list[str] | None:
"""Return a command only when it satisfies the requested operation.
An ordinary prepare asks only for an available runtime, so a verified
existing command is sufficient even when a refresh fails. A forced
prepare asks for replacement; reusing the old command must preserve the
failure and report that operation as unsuccessful.
"""
if not command or (replacement_required and not replacement_completed):
return None
self._install_reason = None
return command
def _remove_managed_runtime_tree_for_replacement(self, path: Path, *, label: str) -> bool:
"""Invalidate cached install facts before removing managed runtime bytes."""
self._invalidate_managed_runtime_projection()
try:
if os.path.lexists(path):
shutil.rmtree(path)
except OSError:
logger.warning("Failed to remove the %s Show Runtime tree before replacement", label, exc_info=True)
self._install_reason = "runtime_install_failed"
return False
if os.path.lexists(path):
self._install_reason = "runtime_install_failed"
return False
return True
def _invalidate_managed_runtime_projection(self) -> None:
self._managed_command = None
self._availability = replace(
self._availability,
install=ShowRuntimeInstallState.ABSENT,
command=None,
install_reason=None,
install_failure_class=None,
install_recovery_action=None,
)
def _install_managed_runtime_locked(
self,
*,
force: bool,
offline: bool,
candidate_validator: Callable[[list[str]], ShowRuntimeStartability] | None = None,
) -> _ManagedInstallAttempt:
command: list[str] | None
if self.runtime_source == _RUNTIME_SOURCE_MANIFEST:
command = (
self._install_manifest_runtime_locked(force=force, offline=offline)
if candidate_validator is None
else self._install_manifest_runtime_locked(
force=force,
offline=offline,
candidate_validator=candidate_validator,
)
)
elif self.runtime_source == _RUNTIME_SOURCE_ARCHIVE:
command = (
self._install_archive_runtime(force=force, offline=offline)
if candidate_validator is None
else self._install_archive_runtime(
force=force,
offline=offline,
candidate_validator=candidate_validator,
)
)
elif self.runtime_source == _RUNTIME_SOURCE_NPM:
command = (
self._install_npm_runtime(force=force)
if candidate_validator is None
else self._install_npm_runtime(
force=force,
candidate_validator=candidate_validator,
)
)
else:
self._install_reason = "runtime_source_unsupported"
return _ManagedInstallAttempt(None, self._install_reason)
if command:
self._download_error = None
return _ManagedInstallAttempt(command)
return _ManagedInstallAttempt(None, self._install_reason or "runtime_install_failed")
def _installed_managed_runtime_command(self, *, offline: bool) -> list[str] | None:
if self.runtime_source == _RUNTIME_SOURCE_MANIFEST:
return self._installed_manifest_runtime_command(offline=offline)
if self.runtime_source == _RUNTIME_SOURCE_ARCHIVE:
return self._installed_archive_runtime_command()
if self.runtime_source == _RUNTIME_SOURCE_NPM:
resolved = _resolve_executable_path(self._managed_bin_path())
command = [resolved] if resolved else None
return command if command and self._retain_managed_command(command) else None
return None
def _safe_installed_managed_runtime_command(self, *, offline: bool) -> list[str] | None:
evidence = self._install_evidence
download_error = self._download_error
try:
return self._installed_managed_runtime_command(offline=offline)
except (OSError, ValueError):
return None
finally:
self._install_evidence = evidence
self._download_error = download_error
def _managed_install_dir_for_command(self, command: Iterable[str]) -> Path | None:
try:
runtime_root = self.runtime_dir.resolve(strict=True)
except (OSError, RuntimeError):
return None
legacy_roots = {
runtime_root / "prebuilt" / "current",
runtime_root / "package",
}
for value in reversed(tuple(command)):
try:
candidate = Path(value).expanduser().resolve(strict=True)
except (OSError, RuntimeError):
continue
parents = (candidate, *candidate.parents) if candidate.is_dir() else candidate.parents
for parent in parents:
if parent == runtime_root:
break
if runtime_root not in parent.parents:
continue
if parent in legacy_roots or (parent / ".vibe-show-runtime.json").is_file():
return parent
return None
def _install_reference_dir(self, install_dir: Path) -> Path:
identity = hashlib.sha256(str(install_dir).encode("utf-8")).hexdigest()
return self.runtime_dir / "references" / identity
def _install_reference_key(self, install_dir: Path) -> tuple[str, str] | None:
try:
resolved = install_dir.resolve(strict=True)
runtime_root = self.runtime_dir.resolve(strict=True)
except (OSError, RuntimeError):
return None
if runtime_root not in resolved.parents:
return None
return str(runtime_root), str(resolved)
def _owns_install_reference(self, key: tuple[str, str]) -> bool:
with _INSTALL_REFERENCE_LOCKS_GUARD:
reference = _INSTALL_REFERENCE_LOCKS.get(key)
return bool(
reference is not None
and self._install_reference_owner in reference.owners
)
def _release_install_reference(self, key: tuple[str, str]) -> None:
released: _ShowRuntimeInstallReference | None = None
with _INSTALL_REFERENCE_LOCKS_GUARD:
reference = _INSTALL_REFERENCE_LOCKS.get(key)
if (
reference is None
or self._install_reference_owner not in reference.owners
):
return
reference.owners.remove(self._install_reference_owner)
if not reference.owners:
released = _INSTALL_REFERENCE_LOCKS.pop(key)
if released is None:
return
try:
_unlock_install_reference(released.handle)
except OSError:
logger.warning("Failed to release Show Runtime install reference", exc_info=True)
try:
released.marker.unlink(missing_ok=True)
except OSError:
logger.warning("Failed to remove Show Runtime install reference", exc_info=True)
@staticmethod
def _reference_path_matches_handle(path: Path, handle: IO[str]) -> bool:
try:
path_info = path.lstat()
open_info = os.fstat(handle.fileno())
except OSError:
return False
return (
_is_exclusive_regular_file(path_info)
and _is_exclusive_regular_file(open_info)
and (path_info.st_dev, path_info.st_ino) == (open_info.st_dev, open_info.st_ino)
)
def _retain_managed_command(self, command: list[str]) -> bool:
install_dir = self._managed_install_dir_for_command(command)
if install_dir is None:
return True
with self._install_guard_locked(timeout_seconds=None) as (acquired, reason):
if not acquired:
self._install_reason = reason or "runtime_install_guard_unavailable"
return False
return self._retain_install_dir_locked(install_dir)
def _retain_install_dir_locked(self, install_dir: Path) -> bool:
key = self._install_reference_key(install_dir)
if key is None:
return False
runtime_root = Path(key[0])
resolved = Path(key[1])
with _INSTALL_REFERENCE_LOCKS_GUARD:
existing = _INSTALL_REFERENCE_LOCKS.get(key)
if existing is not None:
existing.owners.add(self._install_reference_owner)
return True
reference_dir = self._install_reference_dir(resolved)
try:
reference_dir.mkdir(parents=True, exist_ok=True)
reference_info = reference_dir.lstat()
if _is_reparse_point(reference_info) or not stat.S_ISDIR(reference_info.st_mode):
raise OSError("reference directory is not confined")
marker = reference_dir / f"{uuid4().hex}.lock"
flags = os.O_RDWR | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0)
if hasattr(os, "O_NOFOLLOW"):
flags |= os.O_NOFOLLOW
fd = os.open(marker, flags, 0o600)
handle = os.fdopen(fd, "r+", encoding="utf-8")
acquired = False
try:
if not self._reference_path_matches_handle(marker, handle):
raise OSError("reference marker path changed")
handle.seek(0)
if not storage_lock_try_lock(handle):
raise OSError("fresh reference marker is already locked")
acquired = True
handle.seek(0)
handle.write(str(os.getpid()))
handle.flush()
_INSTALL_REFERENCE_LOCKS[key] = _ShowRuntimeInstallReference(
marker=marker,
handle=handle,
owners={self._install_reference_owner},
)
return True
except BaseException:
if acquired:
_unlock_install_reference(handle)
else:
handle.close()
marker.unlink(missing_ok=True)
raise
except Exception:
logger.warning(
"Failed to retain Show Runtime install %s",
resolved,
exc_info=True,
)
self._install_reason = "runtime_install_guard_unavailable"
return False
def _install_dir_has_live_reference(self, install_dir: Path) -> bool:
try:
resolved = install_dir.resolve(strict=True)
runtime_root = self.runtime_dir.resolve(strict=True)
except (OSError, RuntimeError):
return True
key = (str(runtime_root), str(resolved))
with _INSTALL_REFERENCE_LOCKS_GUARD:
if key in _INSTALL_REFERENCE_LOCKS:
return True
reference_dir = self._install_reference_dir(resolved)
try:
info = reference_dir.lstat()
except FileNotFoundError:
return False
except OSError:
return True
if _is_reparse_point(info) or not stat.S_ISDIR(info.st_mode):
return True
try:
with os.scandir(reference_dir) as entries:
markers = sorted(
reference_dir / entry.name
for entry in entries
if _INSTALL_REFERENCE_RE.fullmatch(entry.name)
)
except OSError:
return True
for marker in markers:
try:
marker_info = marker.lstat()
if not _is_exclusive_regular_file(marker_info):
return True
flags = os.O_RDWR | getattr(os, "O_BINARY", 0)
if hasattr(os, "O_NOFOLLOW"):
flags |= os.O_NOFOLLOW
fd = os.open(marker, flags)
handle = os.fdopen(fd, "r+", encoding="utf-8")
except FileNotFoundError:
continue
except OSError:
return True
handle.seek(0)
if not storage_lock_try_lock(handle):
handle.close()
return True
if not self._reference_path_matches_handle(marker, handle):
_unlock_install_reference(handle)
return True
_unlock_install_reference(handle)
marker.unlink(missing_ok=True)
try:
reference_dir.rmdir()
except OSError:
pass
return False
def status(self, *, offline: bool | None = None) -> dict[str, Any]:
"""Inspect install state without turning an unreadable state into absence."""
try:
return self._status(offline=offline)
except (OSError, RecursionError, UnicodeError) as exc:
logger.warning("Show Runtime status inspection failed", exc_info=True)
reason = "runtime_install_inspection_failed"
evidence = ShowRuntimeFailureEvidence(
ShowRuntimeFailureDimension.INSTALL,
reason,
)
availability = ShowRuntimeAvailability.from_install(
install_reason=reason,
install_evidence=evidence,
)
payload = availability.as_payload()
detail = str(exc).strip() or type(exc).__name__
return {
"provider": self.runtime_source,
"platform": runtime_platform_tag(),
"explicit_command": self.command if self._command_explicit else None,
"node_available": None,
"node_version": None,
"node_supported": None,
"manifest": None,
"archive": None,
"install": payload["install"],
"runtime": payload["runtime"],
"command": None,
"reason": reason,
"download_error": None,
"inspection_error": {
"kind": type(exc).__name__,
"message": detail,
},
}
def _status(self, *, offline: bool | None = None) -> dict[str, Any]:
explicit_availability = (
self._resolve_explicit_command_availability()
if self._command_explicit
else None
)
configured_command = explicit_availability.command if explicit_availability else None
effective_offline = self.offline if offline is None else offline
manifest_manager = (
self._shared_manifest_manager(offline=effective_offline)
if explicit_availability is None and self.runtime_source == _RUNTIME_SOURCE_MANIFEST
else None
)
manifest = (
manifest_manager.load_manifest(allow_network=not effective_offline)
if manifest_manager is not None
else None
)
archive: ManagedRuntimeArchive | None = (
manifest_manager.archive_for_platform(manifest)
if manifest_manager is not None and manifest is not None
else None
)
source_manifest_reason = (
manifest_manager._install_reason if manifest_manager is not None else None
)
source_manifest_download_error = (
manifest_manager._download_error if manifest_manager is not None else None
)
disk_install = (
self._shared_manifest_disk_install(manifest_manager, adopt_evidence=False)
if manifest_manager is not None
else None
)
disk_install_reason = (
manifest_manager._install_reason if manifest_manager is not None else None
)
manifest_reason = (
disk_install_reason
if disk_install_reason == "runtime_install_inspection_failed"
else source_manifest_reason
)
manifest_download_error = (
source_manifest_download_error
or (manifest_manager._download_error if manifest_manager is not None else None)
)
platform_tag = runtime_platform_tag()
node = _resolve_node_command()
node_version = _node_version(node) if node else None
minimum_node = (
_ShowManifestRuntimeManager._minimum_node(manifest) if manifest else None
)
node_supported = _node_satisfies_requirement(node_version, minimum_node) if manifest else None
installed_command: list[str] | None = configured_command
installed_dir: Path | None = None
archive_status: dict[str, Any] | None = None
installed_runtime_version: str | None = None
installed_matches: bool | None = None
installed = (
explicit_availability is not None
and explicit_availability.install is ShowRuntimeInstallState.INSTALLED
)
manifest_status = _manifest_status_payload(manifest)
if explicit_availability is None and self.runtime_source == _RUNTIME_SOURCE_MANIFEST:
if disk_install:
installed = True
installed_dir = disk_install.install_dir
installed_command = disk_install.command
installed_runtime_version = _persisted_manifest_runtime_version(disk_install.metadata)
if manifest is not None and archive is not None:
installed_matches = (
manifest_manager.verified_entrypoint(
disk_install.install_dir,
manifest,
archive,
)
is not None
)
if manifest_status is None:
manifest_status = _persisted_manifest_status_payload(disk_install.metadata)
archive_status = _persisted_archive_status_payload(disk_install.metadata)
if archive and disk_install is None:
for candidate in manifest_manager.install_candidates(manifest, archive):
entrypoint = manifest_manager.verified_entrypoint(candidate, manifest, archive)
if entrypoint is None:
continue
installed = True
installed_dir = candidate
installed_runtime_version = manifest.runtime_version
installed_matches = True
if node and node_supported is not False:
installed_command = [*node, str(entrypoint)]
if installed_command:
break
elif explicit_availability is None and self.runtime_source == _RUNTIME_SOURCE_ARCHIVE:
installed_dir = self._archive_install_dir()
installed_command = self._archive_runtime_command(installed_dir, node or ["node"])
installed = installed_command is not None
archive_status = {
"platform": platform_tag,
"name": _runtime_archive_name(),
"url": _redact_download_url(self.archive_url) if not self.archive_path else None,
"path": str(self.archive_path) if self.archive_path else None,
"sha256": None,
"size": None,
}
elif explicit_availability is None and self.runtime_source == _RUNTIME_SOURCE_NPM:
managed = _resolve_executable_path(self._managed_bin_path())
installed_command = [managed] if managed else None
installed = installed_command is not None
installed_dir = self._package_install_dir() if installed else None
if installed and manifest is not None and archive is not None and installed_matches is not True:
installed_matches = False
if (
explicit_availability is None
and manifest_reason == "runtime_install_inspection_failed"
):
evidence = ShowRuntimeFailureEvidence(
ShowRuntimeFailureDimension.INSTALL,
manifest_reason,
)
status_availability = ShowRuntimeAvailability.from_install(
install_reason=manifest_reason,
install_evidence=evidence,
)
elif explicit_availability is not None:
status_availability = explicit_availability
else:
status_availability = ShowRuntimeAvailability.from_install(
command=installed_command,
install=(ShowRuntimeInstallState.INSTALLED if installed else ShowRuntimeInstallState.ABSENT),
install_dir=installed_dir if installed else None,
install_runtime_version=installed_runtime_version,
install_matches_manifest=installed_matches,
)
status_payload = status_availability.as_payload()
install_payload = status_payload["install"]
runtime_payload = status_payload["runtime"]
return {
"provider": self.runtime_source,
"platform": platform_tag,
"explicit_command": self.command if self._command_explicit else None,
"node_available": node is not None,
"node_version": _format_semver(node_version),
"node_supported": node_supported,
"manifest": manifest_status,
"archive": archive_status or _archive_status_payload(archive),
"install": install_payload,
"runtime": runtime_payload,
"command": installed_command,
"reason": (
explicit_availability.reason
if explicit_availability
else manifest_reason or self._install_reason
if manifest_manager is not None
else self._install_reason
),
"download_error": (
None
if explicit_availability
else manifest_download_error or self._download_error
if manifest_manager is not None
else self._download_error
),
}
def probe_archive_reachability(self, *, timeout: float = 10.0) -> dict[str, Any]:
"""Check the selected archive without downloading its body or mutating the cache."""
archive_url: str | None = None
if self.runtime_source == _RUNTIME_SOURCE_MANIFEST:
manager = self._shared_manifest_manager(offline=self.offline)
manifest = manager.load_manifest_for_diagnostics()
if not manifest:
self._adopt_shared_manifest_evidence(manager)
return {
"ok": False,
"checked": False,
"reason": self._install_reason or "runtime_manifest_missing",
"download_error": self._download_error,
}
archive = manager.archive_for_platform(manifest)
if not archive:
self._adopt_shared_manifest_evidence(manager)
return {
"ok": False,
"checked": False,
"reason": self._install_reason or "runtime_platform_unsupported",
}
archive_url = archive.url
elif self.runtime_source == _RUNTIME_SOURCE_ARCHIVE:
if self.archive_path:
return {
"ok": self.archive_path.is_file(),
"checked": True,
"kind": "local_file",
"path": str(self.archive_path),
"reason": None if self.archive_path.is_file() else "runtime_archive_missing",
}
archive_url = self.archive_url
else:
return {
"ok": False,
"checked": False,
"reason": "runtime_archive_probe_not_applicable",
"provider": self.runtime_source,
}
parsed = urllib.parse.urlparse(archive_url)
if parsed.scheme == "file":
path = Path(urllib.request.url2pathname(parsed.path))
return {
"ok": path.is_file(),
"checked": True,
"kind": "local_file",
"url": _redact_download_url(archive_url),
"reason": None if path.is_file() else "runtime_archive_missing",
}
if parsed.scheme != "https":
return {
"ok": False,
"checked": False,
"url": _redact_download_url(archive_url),
"reason": "runtime_archive_url_unsupported",
}
result = probe_url(
archive_url,
timeout=timeout,
opener=urllib.request.urlopen,
user_agent="avibe-show-runtime-doctor",
)
if result.get("reason") == "dependency_probe_unsupported":
result["reason"] = "runtime_archive_probe_unsupported"
elif result.get("reason") == "dependency_download_failed":
result["reason"] = "runtime_archive_download_failed"
return result
@contextlib.contextmanager
def _preview_guard(self):
"""Hold a read-only install guard for the whole preview planning.
The probe lock stays held while staging loops enumerate candidates, so
an install starting after the check cannot slip a live ``manifest-*``
directory into the preview. Yields the busy reason (or ``None`` when
the preview may proceed).
"""
busy = self._preview_busy_reason_locked()
try:
yield busy
finally:
self._release_preview_guard()
def _preview_busy_reason_locked(self) -> str | None:
"""Take the read-only busy probe and keep it for the preview scope."""
reason = self._preview_busy_reason()
if reason is None:
self._preview_guard_fd = getattr(self, "_preview_guard_fd", None)
return reason
def _release_preview_guard(self) -> None:
fd = getattr(self, "_preview_guard_fd", None)
if fd is not None:
if getattr(self, "_preview_guard_msvcrt", False):
unlock_windows_exclusive_lock(fd)
self._preview_guard_msvcrt = False
try:
os.close(fd)
except OSError:
pass
self._preview_guard_fd = None
def _windows_preview_busy_reason(self) -> str | None:
"""Read-only Windows busy probe covering the pre-staging interval.
A leftover ``.install.lock`` is not itself busy — Windows never
deletes it. An installer that already holds ``msvcrt.locking`` on
that file (archive validation, before ``manifest-*`` exists) is.
Staging remains an additional crash-leftover signal.
"""
probe = self._preview_lock_probe()
if probe is not None:
return probe
staging = self._staging_sentinel_reason()
if staging:
return staging
if getattr(self, "_preview_lock_was_absent", False):
return None
try:
flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_NONBLOCK", 0)
fd = os.open(self._install_guard_path, flags)
except OSError:
return "runtime_install_guard_unavailable"
try:
if not try_windows_exclusive_lock(fd):
os.close(fd)
return "runtime_install_already_running"
if not self._guard_path_matches_fd(fd):
os.close(fd)
return "runtime_install_guard_unavailable"
self._preview_guard_fd = fd
self._preview_guard_msvcrt = True
return None
except OSError:
os.close(fd)
return "runtime_install_guard_unavailable"
def _preview_busy_reason(self) -> str | None:
"""Read-only busy probe for previews: never creates or rewrites files.
Detects an active install (same process via the RLock depth, another
process via an advisory lock on an existing ``.install.lock``) so a
preview never advertises a live in-use archive or staging directory
as removable. On POSIX an unopenable-but-existing guard reports
unavailable (an inspection problem). Native Windows has no flock;
the probe instead takes a non-blocking ``msvcrt.locking`` on the
existing lock file (never creating it) and still treats a fresh
``manifest-*``/``prebuilt-*`` directory as busy.
On success the probe fd is kept open with the advisory lock held
(stored on the instance) so the caller can hold the guard through
planning; ``_release_preview_guard`` unlocks and closes it.
"""
if self._install_guard_depth > 0:
return "runtime_install_already_running"
if not fcntl_available():
return self._windows_preview_busy_reason()
import fcntl
probe = self._preview_lock_probe()
if probe is not None:
return probe
if getattr(self, "_preview_lock_was_absent", False):
return None
try:
flags = os.O_RDONLY | getattr(os, "O_NONBLOCK", 0)
fd = os.open(self._install_guard_path, flags)
except OSError:
return "runtime_install_guard_unavailable"
try:
fcntl.flock(fd, fcntl.LOCK_SH | fcntl.LOCK_NB)
# Held (shared) until the preview scope ends: an installer's
# exclusive-lock acquisition now blocks on us and vice versa.
if not self._guard_path_matches_fd(fd):
os.close(fd)
return "runtime_install_guard_unavailable"
self._preview_guard_fd = fd
return None
except OSError:
os.close(fd)
return "runtime_install_already_running"
def _staging_sentinel_reason(self) -> str | None:
"""Treat freshly-modified staging dirs as busy (flock-less platforms)."""
mtime_floor = time.time() - _ARCHIVE_MTIME_GUARD_SECONDS
try:
for pattern in ("manifest-*", "prebuilt-*"):
for path in self.runtime_dir.glob(pattern):
try:
if path.is_dir() and path.stat().st_mtime > mtime_floor:
return "runtime_install_already_running"
except OSError:
continue
except OSError:
return None
return None
def _preview_lock_missing(self) -> bool:
try:
self._install_guard_path.lstat()
except FileNotFoundError:
return True
except OSError:
return False
return False
def _preview_lock_probe(self) -> str | None:
"""Refuse special files before a blocking preview open."""
try:
info = self._install_guard_path.lstat()
except FileNotFoundError:
self._preview_lock_was_absent = True
return None
except OSError:
self._preview_lock_was_absent = False
return "runtime_install_guard_unavailable"
self._preview_lock_was_absent = False
if _is_reparse_point(info) or not _is_exclusive_regular_file(info):
return "runtime_install_guard_unavailable"
return None
def _guard_path_matches_fd(self, fd: int) -> bool:
"""True when the live path still names the locked descriptor."""
try:
open_stat = os.fstat(fd)
path_stat = self._install_guard_path.lstat()
except OSError:
return False
return (
_is_exclusive_regular_file(open_stat)
and _is_exclusive_regular_file(path_stat)
and (open_stat.st_dev, open_stat.st_ino) == (path_stat.st_dev, path_stat.st_ino)
)
def _preview_raced_busy(self) -> bool:
"""True when an install started after a lock-absent preview probe."""
if getattr(self, "_preview_guard_fd", None) is not None:
return False
if self._staging_sentinel_reason():
return True
if not getattr(self, "_preview_lock_was_absent", False):
return False
return not self._preview_lock_missing()
def clean(self, *, keep_previous: int = 1, dry_run: bool = False) -> dict[str, Any]:
if self.runtime_source == _RUNTIME_SOURCE_MANIFEST:
result = self._shared_manifest_manager(offline=True).clean(
keep_previous=keep_previous,
dry_run=dry_run,
)
if "archives" not in result:
reason = result.get("reason")
skipped_reason = (
_SKIPPED_ARCHIVE_REASON_INSTALL_RUNNING
if reason == "runtime_install_already_running"
else _SKIPPED_ARCHIVE_REASON_INSPECTION_FAILED
)
result["archives"] = self._skipped_archive_report(skipped_reason)
return {"dry_run": dry_run, **result}
removed: list[str] = []
try:
if dry_run:
return self._clean_locked(
keep_previous=keep_previous,
dry_run=True,
removed=removed,
)
with self._install_guard_locked(timeout_seconds=1.0) as (acquired, reason):
if not acquired:
skipped_reason = (
_SKIPPED_ARCHIVE_REASON_INSPECTION_FAILED
if reason == "runtime_install_guard_unavailable"
else _SKIPPED_ARCHIVE_REASON_INSTALL_RUNNING
)
return {
"ok": False,
"dry_run": False,
"removed": [],
"reason": reason,
"archives": self._skipped_archive_report(skipped_reason),
}
return self._clean_locked(
keep_previous=keep_previous,
dry_run=False,
removed=removed,
)
except Exception:
# A planning failure (e.g. an install dir disappearing mid-scan)
# must return the structured inspection-failure report, never an
# exception through the CLI or Doctor paths. Staging removals that
# already happened stay in the result so the CLI does not claim
# zero items after files were deleted.
logger.warning("Show Runtime cache cleanup failed", exc_info=True)
return {
"ok": False,
"dry_run": dry_run,
"removed": list(removed),
"archives": self._skipped_archive_report(_SKIPPED_ARCHIVE_REASON_INSPECTION_FAILED),
}
def _clean_locked(
self,
*,
keep_previous: int,
dry_run: bool,
removed: list[str] | None = None,
) -> dict[str, Any]:
if removed is None:
removed = []
preview_guard = self._preview_guard() if dry_run else contextlib.nullcontext(None)
with preview_guard as busy_reason:
if dry_run and busy_reason:
# Map both contention and guard-unavailability through the
# same skip-reason taxonomy the real cleanup uses, so the CLI
# renders reason-specific guidance either way.
skip_reason = (
_SKIPPED_ARCHIVE_REASON_INSPECTION_FAILED
if busy_reason == "runtime_install_guard_unavailable"
else _SKIPPED_ARCHIVE_REASON_INSTALL_RUNNING
)
return {
"ok": False,
"dry_run": True,
"removed": [],
"archives": self._skipped_archive_report(skip_reason),
}
for pattern in ("prebuilt-*", "manifest-*"):
for path in self.runtime_dir.glob(pattern):
if path.is_dir():
if not dry_run:
shutil.rmtree(path, ignore_errors=True)
removed.append(str(path))
if self.runtime_source == _RUNTIME_SOURCE_ARCHIVE:
self._clean_provider_install_dirs(
self.runtime_dir / "prebuilt",
provider=_RUNTIME_SOURCE_ARCHIVE,
keep_previous=keep_previous,
dry_run=dry_run,
removed=removed,
)
elif self.runtime_source == _RUNTIME_SOURCE_NPM:
self._clean_provider_install_dirs(
self.runtime_dir / "package",
provider=_RUNTIME_SOURCE_NPM,
keep_previous=keep_previous,
dry_run=dry_run,
removed=removed,
)
archives = self._clean_downloaded_archives(dry_run=dry_run)
if dry_run and self._preview_raced_busy():
return {
"ok": False,
"dry_run": True,
"removed": [],
"archives": self._skipped_archive_report(_SKIPPED_ARCHIVE_REASON_INSTALL_RUNNING),
}
return {
"ok": True,
"dry_run": dry_run,
"removed": removed,
"archives": archives,
}
def _clean_provider_install_dirs(
self,
namespace: Path,
*,
provider: str,
keep_previous: int,
dry_run: bool,
removed: list[str],
) -> None:
versions_dir = namespace / "versions"
try:
versions_info = versions_dir.lstat()
except FileNotFoundError:
return
if _is_reparse_point(versions_info) or not stat.S_ISDIR(versions_info.st_mode):
raise OSError(f"runtime versions directory is not confined: {versions_dir}")
pointer_path = namespace / "current.json"
try:
pointer = json.loads(pointer_path.read_text(encoding="utf-8"))
current = Path(pointer["install_dir"]).expanduser().resolve(strict=True)
resolved_versions = versions_dir.resolve(strict=True)
except FileNotFoundError:
return
except (KeyError, OSError, RuntimeError, TypeError, UnicodeError, ValueError) as exc:
raise OSError(f"runtime pointer is unreadable: {pointer_path}") from exc
if pointer.get("provider") != provider or current.parent != resolved_versions:
raise OSError(f"runtime pointer is not confined: {pointer_path}")
records: list[tuple[Path, float]] = []
with os.scandir(versions_dir) as entries:
for entry in entries:
try:
if not entry.is_dir(follow_symlinks=False):
continue
path = Path(entry.path)
resolved = path.resolve(strict=True)
if resolved.parent != resolved_versions:
continue
metadata = json.loads(
(path / ".vibe-show-runtime.json").read_text(encoding="utf-8")
)
if (
metadata.get("provider") != provider
or metadata.get("runtime_id") != "show-runtime"
):
continue
records.append((path, entry.stat(follow_symlinks=False).st_mtime))
except FileNotFoundError:
continue
except (OSError, RuntimeError, UnicodeError, ValueError) as exc:
raise OSError(f"runtime install cannot be inspected: {entry.path}") from exc
protected = {current}
ranked: list[tuple[Path, float]] = []
for path, mtime in records:
resolved = path.resolve(strict=True)
if self._install_dir_has_live_reference(resolved):
protected.add(resolved)
else:
ranked.append((path, mtime))
rollback = sorted(
(item for item in ranked if item[0].resolve(strict=True) != current),
key=lambda item: item[1],
reverse=True,
)
protected.update(
path.resolve(strict=True)
for path, _mtime in rollback[: max(0, keep_previous)]
)
for path, _mtime in records:
if path.resolve(strict=True) in protected:
continue
if not dry_run:
shutil.rmtree(path)
removed.append(str(path))
def archive_cache_status(self, *, keep_previous: int = 1) -> dict[str, Any]:
"""Report reclaimable content-addressed archives without deleting anything.
Simulates the install-dir cleanup a real ``clean(keep_previous=...)``
would perform, so the reported candidates match what reclamation would
actually remove. Failures in either phase return the structured
inspection-failure report so Doctor can render them.
"""
report = self.clean(keep_previous=keep_previous, dry_run=True)
archives = report.get("archives") or self._skipped_archive_report(_SKIPPED_ARCHIVE_REASON_INSPECTION_FAILED)
return archives
@staticmethod
def _iter_install_metadata(versions_dir: Path, pattern: str) -> Iterator[Path]:
"""Glob install metadata with error-preserving traversal.
``Path.glob`` suppresses per-directory OSError and silently omits
retained installs whose subtree cannot be scanned; that would unprotect
their rollback archives, so traversal failures raise instead.
"""
try:
parts = pattern.split("/")
current: Iterable[Path] = [versions_dir]
for depth, part in enumerate(parts):
is_last = depth == len(parts) - 1
next_paths: list[Path] = []
for parent in current:
try:
iterator = os.scandir(parent)
except FileNotFoundError:
continue
except NotADirectoryError:
# An unrelated non-directory matched a wildcard level
# (e.g. .DS_Store under versions/); skip it rather
# than disabling archive reporting for the cache.
continue
except OSError as exc:
raise _ArchiveInspectionError(f"versions traversal failed: {parent}") from exc
try:
for entry in iterator:
if not fnmatch.fnmatch(entry.name, part):
continue
if not is_last and not entry.is_dir(follow_symlinks=False):
# Intermediate wildcard levels must be
# directories; files/symlinks are not installs.
continue
child = parent / entry.name
next_paths.append(child)
except OSError as exc:
raise _ArchiveInspectionError(f"versions traversal failed: {parent}") from exc
finally:
iterator.close()
current = next_paths
for path in current:
if path.name == ".vibe-show-runtime.json":
yield path
except _ArchiveInspectionError:
raise
def _protected_archive_sha256s(self, skip_metadata_under: set[Path] | None = None) -> set[str]:
"""SHA-256 digests of archives the current and retained installs still need.
Sources: the ``current.json`` pointer plus every remaining managed
install's ``.vibe-show-runtime.json`` metadata. Called after
install-dir cleanup, so the remaining metadata files are exactly the
current install plus the retained rollback install(s). Metadata under
``skip_metadata_under`` is ignored, so dry runs can simulate the state
after removing those install dirs.
Raises ``_ArchiveMetadataError`` when a retained install's metadata is
unreadable or malformed: silently treating that archive as unprotected
could delete the artifact a rollback reinstall needs.
"""
skip_resolved = {path.resolve() for path in (skip_metadata_under or ())}
def _skipped(metadata_path: Path) -> bool:
if not skip_resolved:
return False
resolved = metadata_path.resolve()
return any(resolved == item or item in resolved.parents for item in skip_resolved)
protected: set[str] = set()
try:
pointer = json.loads((self.runtime_dir / "current.json").read_text(encoding="utf-8"))
digest = pointer.get("archive_sha256")
if isinstance(digest, str) and _CONTENT_ADDRESSED_ARCHIVE_RE.fullmatch(f"{digest}.tgz"):
protected.add(digest)
except FileNotFoundError:
pass
except Exception as cop:
raise _ArchiveMetadataError("current.json is unreadable") from cop
if self.archive_path is not None:
try:
archive_name = self.archive_path.resolve().name
except OSError:
archive_name = self.archive_path.name
if _CONTENT_ADDRESSED_ARCHIVE_RE.fullmatch(archive_name):
protected.add(archive_name[: -len(".tgz")])
versions_dir = self.runtime_dir / "versions"
if versions_dir.is_symlink():
raise _ArchiveMetadataError("versions directory is a symlink")
try:
# Path.is_dir()/exists() suppress OSError into False; an
# uninspectable versions tree must instead fail closed so every
# retained install keeps its rollback archive protected.
versions_is_dir = stat.S_ISDIR(versions_dir.stat().st_mode)
except FileNotFoundError:
versions_is_dir = False
except OSError as exc:
raise _ArchiveInspectionError("versions directory cannot be inspected") from exc
if versions_is_dir:
for pattern in ("*/*/.vibe-show-runtime.json", "*/*/*/.vibe-show-runtime.json"):
for metadata_path in self._iter_install_metadata(versions_dir, pattern):
if _skipped(metadata_path):
continue
try:
metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
except Exception as exc:
raise _ArchiveMetadataError(f"install metadata is unreadable: {metadata_path}") from exc
digest = metadata.get("archive_sha256")
if not _CONTENT_ADDRESSED_ARCHIVE_RE.fullmatch(
f"{digest}.tgz" if isinstance(digest, str) else ""
):
raise _ArchiveMetadataError(
f"install metadata archive_sha256 is missing or not a digest: {metadata_path}"
)
protected.add(digest)
return protected
def _archive_cleanup_candidates(self, protected: set[str]) -> list[tuple[Path, int, str, int]]:
"""Completed content-addressed archives outside the protected set.
Only strict ``<sha256>.tgz`` regular files are candidates. The manifest
download flow stages into ``<sha256>.tmp`` and atomically renames only
after size + checksum verification, so a matching name implies a
completed, verified archive; in-progress ``.tmp`` downloads, symlinks,
and unknown file names are never candidates. Archives modified within
the cross-process safety window are also skipped: another process may
have just finalized a download whose install metadata does not exist
yet.
"""
downloads_dir = self.runtime_dir / "downloads"
# Windows tuples carry an extra inode field for identity checks;
# POSIX tuples pad it so both branches share one unpack shape.
candidates: list[tuple[Path, int, str, int]] = []
try:
downloads_stat = downloads_dir.lstat() # error-preserving, no follow
exists = True
except FileNotFoundError:
exists = False
except OSError as exc:
raise _ArchiveInspectionError("downloads directory cannot be inspected") from exc
if not exists:
return candidates
# A symlink or reparse-point downloads directory would follow the
# link and unlink files outside Avibe's runtime state; fail as an
# inspection error rather than traverse it.
if _is_reparse_point(downloads_stat) or not stat.S_ISDIR(downloads_stat.st_mode):
raise _ArchiveInspectionError("downloads directory is a symlink or not a directory")
mtime_floor = time.time() - _ARCHIVE_MTIME_GUARD_SECONDS
if os.name == "nt":
# Directory descriptors (dir_fd) are unsupported on native
# Windows, so scan/stat/unlink by path. Bind the scan to the
# validated directory identity (dev/ino) so a junction swap of
# ``downloads`` cannot redirect enumeration or later deletion.
downloads_identity = (downloads_stat.st_dev, downloads_stat.st_ino)
def _require_same_downloads() -> None:
try:
current = downloads_dir.lstat()
except OSError as exc:
raise _ArchiveInspectionError("downloads directory cannot be inspected") from exc
if _is_reparse_point(current) or not stat.S_ISDIR(current.st_mode):
raise _ArchiveInspectionError("downloads directory is a symlink or not a directory")
if (current.st_dev, current.st_ino) != downloads_identity:
raise _ArchiveInspectionError("downloads directory was replaced")
_require_same_downloads()
iterator = os.scandir(downloads_dir)
try:
for entry in iterator:
is_claim = bool(_ABANDONED_ARCHIVE_CLAIM_RE.fullmatch(entry.name))
if not is_claim and not _CONTENT_ADDRESSED_ARCHIVE_RE.fullmatch(entry.name):
continue
try:
entry_stat = entry.stat(follow_symlinks=False)
except FileNotFoundError:
continue
except OSError as cop:
raise _ArchiveInspectionError(f"archive is not stat-able: {entry.name}") from cop
if not stat.S_ISREG(entry_stat.st_mode):
continue
if not is_claim:
if entry_stat.st_mtime > mtime_floor:
continue
if entry.name[: -len(".tgz")] in protected:
continue
candidates.append(
(downloads_dir / entry.name, entry_stat.st_size, entry.name, entry_stat.st_ino)
)
finally:
iterator.close()
_require_same_downloads()
self._downloads_dir_identity = downloads_identity
return candidates
# POSIX: bind enumeration and unlinking to the directory we validated
# so a concurrent path swap (symlink replacing ``downloads`` between
# the stat above and iterdir/unlink below) cannot redirect operations.
dir_fd = os.open(downloads_dir, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_DIRECTORY", 0))
try:
opened = os.fstat(dir_fd)
if (opened.st_dev, opened.st_ino) != (downloads_stat.st_dev, downloads_stat.st_ino):
raise _ArchiveInspectionError("downloads directory was replaced before scan")
with os.scandir(dir_fd) as entries:
names = [entry.name for entry in entries]
for name in sorted(names):
is_claim = bool(_ABANDONED_ARCHIVE_CLAIM_RE.fullmatch(name))
if not is_claim and not _CONTENT_ADDRESSED_ARCHIVE_RE.fullmatch(name):
continue
try:
stat_result = os.stat(name, dir_fd=dir_fd, follow_symlinks=False)
except FileNotFoundError:
continue
except OSError as cop:
raise _ArchiveInspectionError(f"archive is not stat-able: {name}") from cop
if not stat.S_ISREG(stat_result.st_mode):
continue
if not is_claim:
if stat_result.st_mtime > mtime_floor:
continue
if name[: -len(".tgz")] in protected:
continue
candidates.append((downloads_dir / name, stat_result.st_size, name, 0))
# Keep the enumeration descriptor until the caller closes it so
# the removal phase (when any) unlinks through the same fd.
# Dry runs, Doctor, and empty real scans close it in
# ``_clean_downloaded_archives``.
self._downloads_dir_fd = dir_fd
return candidates
except BaseException:
os.close(dir_fd)
raise
def _close_downloads_dir_fd(self) -> None:
fd = getattr(self, "_downloads_dir_fd", None)
if fd is not None:
try:
os.close(fd)
except OSError:
pass
self._downloads_dir_fd = None
def _clean_downloaded_archives(
self,
*,
dry_run: bool = False,
skip_metadata_under: set[Path] | None = None,
) -> dict[str, Any]:
"""Report on / prune the content-addressed archive cache.
Dry runs are strictly read-only: they never take the install guard,
never create or rewrite ``.install.lock``, and stay usable on a
read-only runtime directory (Doctor contract). Real cleanup serializes
against installs via the guard (re-entrant inside an install) and
reports one of two skip reasons: lock contention, or inspection
failure — consumers key off ``skipped_reason`` alone.
"""
if dry_run:
try:
protected = self._protected_archive_sha256s(skip_metadata_under=skip_metadata_under)
candidates = self._archive_cleanup_candidates(protected)
except Exception:
logger.warning("Show Runtime archive cleanup inspection failed", exc_info=True)
return self._skipped_archive_report(_SKIPPED_ARCHIVE_REASON_INSPECTION_FAILED)
finally:
# Dry runs never delete, so the enumeration descriptor (kept
# for the removal phase) must be closed on every path.
self._close_downloads_dir_fd()
return {
"outcome": "cleaned" if not candidates else "partial",
"protected_count": len(protected),
"candidate_count": len(candidates),
"candidate_bytes": sum(size for _, size, _name, _ino in candidates),
"removed_count": 0,
"removed_bytes": 0,
"failed_count": 0,
}
with self._install_guard_locked(timeout_seconds=1.0) as (acquired, guard_reason):
if not acquired:
logger.warning("Show Runtime archive cleanup skipped: install guard %s", guard_reason)
if guard_reason == "runtime_install_guard_unavailable":
return self._skipped_archive_report(_SKIPPED_ARCHIVE_REASON_INSPECTION_FAILED)
return self._skipped_archive_report(_SKIPPED_ARCHIVE_REASON_INSTALL_RUNNING)
try:
protected = self._protected_archive_sha256s(skip_metadata_under=skip_metadata_under)
candidates = self._archive_cleanup_candidates(protected)
removed_count = 0
removed_bytes = 0
failed_count = 0
# Unlink through the same validated directory on POSIX (no
# path resolution that a concurrent swap could redirect); on
# Windows unlink by path. A fresh runtime with no candidates
# never opens the directory at all.
if candidates:
candidates.sort(key=lambda item: (0 if _ABANDONED_ARCHIVE_CLAIM_RE.fullmatch(item[2]) else 1, item[2]))
if os.name == "nt":
downloads_identity = getattr(self, "_downloads_dir_identity", None)
for path, size, name, inode in candidates:
is_claim = bool(_ABANDONED_ARCHIVE_CLAIM_RE.fullmatch(name))
claimed = path if is_claim else path.with_name(f"{name}.avibe-removing")
try:
if downloads_identity is not None:
dir_stat = path.parent.lstat()
if _is_reparse_point(dir_stat) or (
dir_stat.st_dev,
dir_stat.st_ino,
) != downloads_identity:
raise OSError("downloads directory was replaced")
pre_stat = os.stat(path, follow_symlinks=False)
if inode and pre_stat.st_ino != inode:
raise OSError("entry was replaced after enumeration")
if not stat.S_ISREG(pre_stat.st_mode):
raise OSError("entry replaced by a non-regular file")
if is_claim:
os.unlink(path)
else:
os.rename(path, claimed)
post_stat = os.stat(claimed, follow_symlinks=False)
if inode and post_stat.st_ino != inode:
os.rename(claimed, path)
raise OSError("rename claimed a different entry")
os.unlink(claimed)
except OSError:
logger.warning("Failed to remove stale Show Runtime archive %s", path, exc_info=True)
failed_count += 1
try:
if not is_claim and claimed.exists():
os.rename(claimed, path)
except OSError:
pass
continue
removed_count += 1
removed_bytes += size
else:
dir_fd = getattr(self, "_downloads_dir_fd", None)
try:
for path, size, name, _inode in candidates:
try:
os.unlink(name, dir_fd=dir_fd)
except OSError:
logger.warning("Failed to remove stale Show Runtime archive %s", path, exc_info=True)
failed_count += 1
continue
removed_count += 1
removed_bytes += size
finally:
if dir_fd is not None:
os.close(dir_fd)
self._downloads_dir_fd = None
report = {
"protected_count": len(protected),
"candidate_count": len(candidates),
"candidate_bytes": sum(size for _, size, _name, _ino in candidates),
"removed_count": removed_count,
"removed_bytes": removed_bytes,
"failed_count": failed_count,
}
if failed_count:
report["outcome"] = "skipped" if removed_count == 0 else "partial"
report["skipped_reason"] = _SKIPPED_ARCHIVE_REASON_REMOVAL_FAILED
else:
report["outcome"] = "cleaned"
return report
except Exception:
logger.warning("Show Runtime archive cleanup failed", exc_info=True)
return self._skipped_archive_report(_SKIPPED_ARCHIVE_REASON_INSPECTION_FAILED)
finally:
# Empty real scans never enter the unlink branch that closes
# the enumeration descriptor; close it on every remaining path.
self._close_downloads_dir_fd()
@staticmethod
def _skipped_archive_report(reason: str) -> dict[str, Any]:
return {
"outcome": "skipped",
"protected_count": 0,
"candidate_count": 0,
"candidate_bytes": 0,
"removed_count": 0,
"removed_bytes": 0,
"skipped_reason": reason,
}
def prepare(
self,
*,
force: bool | None = None,
offline: bool | None = None,
automatic: bool = False,
) -> dict[str, Any]:
return self._prepare(
force=force,
offline=offline,
automatic=automatic,
)
def _prepare(
self,
*,
force: bool | None,
offline: bool | None,
automatic: bool,
candidate_validator: Callable[[list[str]], ShowRuntimeStartability] | None = None,
) -> dict[str, Any]:
effective_force = self.force_install if force is None else force
effective_offline = self.offline if offline is None else offline
if candidate_validator is None:
admission, operation = self._attempt_managed_install(
force=effective_force,
offline=effective_offline,
automatic=automatic,
)
else:
admission, operation = self._attempt_managed_install(
force=effective_force,
offline=effective_offline,
automatic=automatic,
candidate_validator=candidate_validator,
)
payload = admission.as_payload()
payload["ok"] = operation.ok
if not operation.ok:
payload["reason"] = operation.reason
status_offline = True if admission.policy is ShowRuntimePolicyState.SKIPPED else effective_offline
payload.update(
{
"provider": self.runtime_source,
"platform": runtime_platform_tag(),
"status": self.status(offline=status_offline),
}
)
return payload
def _verify_startability(self, command_value: Any) -> ShowRuntimeStartability:
command = command_value if isinstance(command_value, list) else []
if not command:
return ShowRuntimeStartability.not_startable("runtime_command_missing")
try:
with tempfile.TemporaryDirectory(
prefix="avibe-show-runtime-repair-"
) as verification_root_value:
verification_root = Path(verification_root_value)
verifier = ShowRuntimeManager(
command=shlex.join(str(part) for part in command),
workspace_root=verification_root / "show",
runtime_dir=verification_root / "runtime",
auto_install=False,
)
try:
result = asyncio.run(verifier.ensure())
finally:
verifier.stop()
except Exception as exc: # noqa: BLE001
detail = str(exc).strip() or type(exc).__name__
return ShowRuntimeStartability.undetermined(detail)
if result.available:
return ShowRuntimeStartability.startable()
return ShowRuntimeStartability.not_startable(
result.reason or "runtime_start_failed"
)
def repair(self) -> dict[str, Any]:
"""Verify startability, then publish only a startable replacement."""
before = self.status()
before_install = (
before.get("install") if isinstance(before.get("install"), dict) else {}
)
before_installed = before_install.get("state") == "installed"
before_install_dir = before_install.get("install_dir")
provider = before.get("provider")
platform_tag = before.get("platform")
def outcome(
state: str,
*,
ok: bool,
reason: str | None = None,
verification: ShowRuntimeStartability | None = None,
verification_phase: str | None = None,
repair_attempted: bool = False,
prepared: Mapping[str, Any] | None = None,
) -> dict[str, Any]:
prepared_status = (
prepared.get("status")
if prepared is not None and isinstance(prepared.get("status"), dict)
else {}
)
prepared_install = (
prepared_status.get("install")
if isinstance(prepared_status.get("install"), dict)
else before_install
)
download_error = (
prepared_status.get("download_error")
if isinstance(prepared_status.get("download_error"), dict)
else before.get("download_error")
)
return {
"ok": ok,
"outcome": state,
"reason": reason,
"verification": verification.as_payload() if verification else None,
"verification_phase": verification_phase,
"repair_attempted": repair_attempted,
"was_installed": before_installed,
"provider": (
prepared.get("provider") if prepared is not None else provider
),
"platform": (
prepared.get("platform") if prepared is not None else platform_tag
),
"install_dir": prepared_install.get("install_dir"),
"installed": prepared_install.get("state") == "installed",
"command": (
prepared_status.get("command")
if prepared is not None
else before.get("command")
),
"download_error": download_error,
"start_error": verification.detail if verification else None,
"explicit_command": before.get("explicit_command"),
"archive_url": (
before.get("archive", {}).get("url")
if isinstance(before.get("archive"), dict)
else None
),
"before_install_dir": before_install_dir,
"inspection_error": before.get("inspection_error"),
}
if (
before_install.get("state") == "failed"
and before.get("reason") == "runtime_install_inspection_failed"
):
return outcome(
"failed",
ok=False,
reason="runtime_install_inspection_failed",
)
if before_installed:
command = before.get("command")
if isinstance(command, list) and not self._retain_managed_command(command):
verification = ShowRuntimeStartability.undetermined(
self._install_reason or "runtime_install_guard_unavailable"
)
return outcome(
"failed",
ok=False,
reason="runtime_start_verification_failed",
verification=verification,
verification_phase="before",
)
verification = self._verify_startability(command)
if verification.state is ShowRuntimeStartabilityState.UNDETERMINED:
return outcome(
"failed",
ok=False,
reason="runtime_start_verification_failed",
verification=verification,
verification_phase="before",
)
if verification.state is ShowRuntimeStartabilityState.STARTABLE:
return outcome(
"healthy",
ok=True,
verification=verification,
verification_phase="before",
)
if before.get("explicit_command"):
return outcome(
"failed",
ok=False,
reason=verification.reason or "runtime_start_failed",
verification=verification,
verification_phase="before",
)
archive = before.get("archive") if isinstance(before.get("archive"), dict) else {}
archive_url = str(archive.get("url") or "")
if (
before.get("provider") == _RUNTIME_SOURCE_ARCHIVE
and "github.com/avibe-bot/vibe-show-runtime/releases/latest/download/"
in archive_url
):
return outcome(
"failed",
ok=False,
reason="runtime_legacy_archive_unavailable",
verification=(verification if before_installed else None),
verification_phase=("before" if before_installed else None),
)
candidate_verification: ShowRuntimeStartability | None = None
def validate_candidate(command: list[str]) -> ShowRuntimeStartability:
nonlocal candidate_verification
candidate_verification = self._verify_startability(command)
return candidate_verification
prepared = self._prepare(
force=before_installed,
offline=None,
automatic=False,
candidate_validator=validate_candidate,
)
if prepared.get("ok") and candidate_verification is not None:
return outcome(
"repaired",
ok=True,
verification=candidate_verification,
verification_phase="after",
repair_attempted=True,
prepared=prepared,
)
reason = str(prepared.get("reason") or "runtime_prepare_failed")
return outcome(
"failed",
ok=False,
reason=reason,
verification=(
candidate_verification
if candidate_verification is not None
else verification
if before_installed
else None
),
verification_phase=(
"after"
if candidate_verification is not None
else "before"
if before_installed
else None
),
repair_attempted=True,
prepared=prepared,
)
def _configured_manifest_source(self) -> str:
if self.manifest_path is not None:
return str(self.manifest_path)
if self.manifest_url is not None:
return self.manifest_url
return _PACKAGED_RUNTIME_MANIFEST_SOURCE
def _installed_manifest_runtime_command(self, *, offline: bool | None = None) -> list[str] | None:
node = _resolve_node_command()
if not node:
return None
manager = self._shared_manifest_manager(offline=self.offline if offline is None else offline)
entrypoint = manager.resolve_selected_entrypoint()
if entrypoint is not None:
self._adopt_shared_manifest_evidence(manager)
command = [*node, str(entrypoint)]
return command if self._retain_managed_command(command) else None
source_reason = manager._install_reason
source_download_error = manager._download_error
if source_reason not in {
"runtime_manifest_download_failed",
"runtime_manifest_invalid",
"runtime_manifest_missing",
"runtime_manifest_unavailable_offline",
}:
self._adopt_shared_manifest_evidence(manager)
return None
disk_install = self._shared_manifest_disk_install(manager, adopt_evidence=False)
manager._install_reason = source_reason
manager._download_error = source_download_error
self._adopt_shared_manifest_evidence(manager)
command = disk_install.command if disk_install else None
return command if command and self._retain_managed_command(command) else None
def _shared_manifest_disk_install(
self,
manager: _ShowManifestRuntimeManager,
*,
adopt_evidence: bool = True,
) -> _ShowRuntimeDiskInstall | None:
admitted_entrypoint = manager.resolve_binary()
if adopt_evidence:
self._adopt_shared_manifest_evidence(manager)
if admitted_entrypoint is None:
return None
try:
pointer = json.loads((self.runtime_dir / "current.json").read_text(encoding="utf-8"))
install_dir = Path(pointer["install_dir"]).resolve(strict=True)
metadata = json.loads(
(install_dir / manager.spec.metadata_filename).read_text(encoding="utf-8")
)
status_metadata = dict(metadata)
status_metadata["manifest_sha256"] = pointer["manifest_sha256"]
except (KeyError, OSError, RuntimeError, TypeError, ValueError):
return None
entrypoint = manager._project_entrypoint(install_dir)
if not entrypoint.is_file():
return None
node = _resolve_node_command()
command = [*node, str(entrypoint)] if node else None
return _ShowRuntimeDiskInstall(
install_dir=install_dir,
command=command,
metadata=status_metadata,
)
def _shared_manifest_manager(self, *, offline: bool) -> _ShowManifestRuntimeManager:
return _ShowManifestRuntimeManager(self, offline=offline)
def _adopt_shared_manifest_evidence(
self,
manager: _ShowManifestRuntimeManager,
result: Mapping[str, Any] | None = None,
) -> None:
reason = result.get("reason") if result is not None else manager._install_reason
download_error = (
result.get("download_error") if result is not None else manager._download_error
)
self._download_error = download_error if isinstance(download_error, dict) else None
if reason:
provenance = "configured" if self.manifest_path or self.manifest_url else "packaged"
retryable = (
self._download_error.get("retryable")
if self._download_error is not None
else None
)
self._record_install_failure(
str(reason),
provenance=provenance,
retryable=retryable if isinstance(retryable, bool) else None,
)
else:
self._install_reason = None
@contextlib.contextmanager
def _install_guard_locked(self, *, timeout_seconds: float | None = 0.0):
"""Serialize installs and archive cleanup, across processes too.
Yields a ``(acquired, reason)`` pair. ``acquired`` is True when the
guard is held; otherwise ``reason`` distinguishes contention
(``runtime_install_already_running``) from a guard that cannot exist
(``runtime_install_guard_unavailable``: read-only/full directory,
symlinked or hard-linked lock file). The outermost caller in this
process takes the cross-process file lock; nested calls on the same
thread (post-install cleanup runs inside the install) reuse it, so the
non-re-entrant ``flock`` never deadlocks against itself.
"""
unavailable = (False, "runtime_install_guard_unavailable")
busy = (False, "runtime_install_already_running")
with self._install_guard:
if self._install_guard_depth > 0:
self._install_guard_depth += 1
try:
yield (True, None)
finally:
self._install_guard_depth -= 1
return
# A symlinked lock path would make the lock truncate/rewrite a
# file outside the runtime directory; a hard link shares its
# inode with unrelated content. Refuse both before any open.
try:
guard_lstat = self._install_guard_path.lstat()
if not _is_exclusive_regular_file(guard_lstat):
logger.warning(
"Show Runtime install guard %s is a symlink or hard link; refusing to lock",
self._install_guard_path,
)
yield unavailable
return
except FileNotFoundError:
pass
except OSError:
logger.warning(
"Show Runtime install guard %s cannot be inspected; refusing to lock",
self._install_guard_path,
exc_info=True,
)
yield unavailable
return
# Open the guard ourselves with no-follow semantics so a raced
# replacement (symlink/hard link swapped in after the lstat) can
# never be truncated by MigrationFileLock's append-open; we then
# validate the descriptor and hand the same handle's fd to the
# lock so validation and locking cover one identical inode.
guard_dir = self._install_guard_path.parent
try:
guard_dir.mkdir(parents=True, exist_ok=True)
guard_flags = os.O_RDWR | os.O_CREAT
if hasattr(os, "O_NOFOLLOW"):
guard_flags |= os.O_NOFOLLOW
lock_fd = os.open(self._install_guard_path, guard_flags, 0o644)
except OSError as exc:
if exc.errno == errno.ELOOP:
logger.warning("Show Runtime install guard %s is a symlink; refusing to lock", self._install_guard_path)
yield unavailable
return
logger.warning(
"Show Runtime install guard %s is unavailable",
self._install_guard_path,
exc_info=True,
)
yield unavailable
return
try:
if not self._guard_path_matches_fd(lock_fd):
logger.warning(
"Show Runtime install guard descriptor is not an exclusive regular file; refusing",
)
os.close(lock_fd)
yield unavailable
return
file_lock = MigrationFileLock(self._install_guard_path, timeout_seconds=timeout_seconds)
handle = os.fdopen(lock_fd, "a+", encoding="utf-8")
deadline = (
None
if timeout_seconds is None
else time.monotonic() + timeout_seconds
)
while True:
handle.seek(0)
if storage_lock_try_lock(handle):
handle.seek(0)
handle.truncate()
handle.write(str(os.getpid()))
handle.flush()
file_lock.adopt_locked_handle(handle)
break
if deadline is not None and time.monotonic() >= deadline:
handle.close()
yield busy
return
time.sleep(0.1)
if not self._guard_path_matches_fd(handle.fileno()):
logger.warning(
"Show Runtime install guard path was replaced after lock acquisition; refusing",
)
file_lock.release()
yield unavailable
return
except OSError:
logger.warning(
"Show Runtime install guard %s could not be locked",
self._install_guard_path,
exc_info=True,
)
yield unavailable
return
except OSError:
# A lock file that cannot be created/opened (read-only or full
# runtime directory) is a structured "cannot serialize" outcome,
# never an exception through prepare/clean.
logger.warning(
"Show Runtime install guard %s is unavailable; treating as busy",
self._install_guard_path,
exc_info=True,
)
yield unavailable
return
self._install_guard_depth = 1
try:
yield (True, None)
finally:
self._install_guard_depth = 0
try:
file_lock.release()
except Exception:
logger.warning("Failed to release Show Runtime install guard", exc_info=True)
def _install_manifest_runtime_locked(
self,
*,
force: bool,
offline: bool,
candidate_validator: Callable[[list[str]], ShowRuntimeStartability] | None = None,
) -> list[str] | None:
node = _resolve_node_command()
if not node:
self._install_reason = "runtime_node_missing"
return None
if force:
self._invalidate_managed_runtime_projection()
manager = self._shared_manifest_manager(offline=offline)
retained_publication_key: tuple[str, str] | None = None
def validate_entrypoint(entrypoint: Path) -> str | None:
nonlocal retained_publication_key
command = [*node, str(entrypoint)]
if candidate_validator is not None:
outcome = candidate_validator(command)
if outcome.state is ShowRuntimeStartabilityState.NOT_STARTABLE:
return outcome.reason or "runtime_start_failed"
if outcome.state is ShowRuntimeStartabilityState.UNDETERMINED:
return "runtime_start_verification_failed"
install_dir = self._managed_install_dir_for_command(command)
key = self._install_reference_key(install_dir) if install_dir else None
if key is None:
return "runtime_install_guard_unavailable"
already_owned = self._owns_install_reference(key)
if not self._retain_install_dir_locked(install_dir):
return self._install_reason or "runtime_install_guard_unavailable"
if not already_owned:
retained_publication_key = key
return None
result = manager.ensure(
force=force,
validate_candidate=validate_entrypoint,
)
if not result.get("ok") and retained_publication_key is not None:
self._release_install_reference(retained_publication_key)
self._adopt_shared_manifest_evidence(manager, result)
entrypoint = manager.installed_result_entrypoint(result)
if (
not force
and result.get("reason") == "runtime_install_guard_unavailable"
):
entrypoint = manager.resolve_selected_entrypoint()
command = [*node, str(entrypoint)] if entrypoint is not None else None
return self._managed_install_operation_command(
command,
replacement_required=force,
replacement_completed=bool(force and result.get("changed")),
)
def _installed_archive_runtime_command(self) -> list[str] | None:
node = _resolve_node_command()
if not node:
return None
command = self._archive_runtime_command(self._archive_install_dir(), node)
return command if command and self._retain_managed_command(command) else None
def _install_archive_runtime(
self,
*,
force: bool,
offline: bool | None = None,
candidate_validator: Callable[[list[str]], ShowRuntimeStartability] | None = None,
) -> list[str] | None:
node = _resolve_node_command()
if not node:
self._install_reason = "runtime_node_missing"
return None
self.runtime_dir.mkdir(parents=True, exist_ok=True)
install_dir = self._archive_install_dir()
existing_command = self._archive_runtime_command(install_dir, node)
if existing_command and not self._retain_managed_command(existing_command):
existing_command = None
archive = self._resolve_prebuilt_archive(offline=offline)
if not archive:
return self._managed_install_operation_command(
existing_command,
replacement_required=force,
)
archive_digest = file_sha256(archive)
if not force and existing_command and self._archive_manifest_matches(archive_digest):
if candidate_validator is not None:
validation = candidate_validator(existing_command)
if validation.state is not ShowRuntimeStartabilityState.STARTABLE:
self._install_reason = self._startability_failure_reason(validation)
return None
return self._managed_install_operation_command(
existing_command,
replacement_required=False,
)
tmp_dir = Path(tempfile.mkdtemp(prefix="prebuilt-", dir=self.runtime_dir))
candidate_dir: Path | None = None
retained_publication_key: tuple[str, str] | None = None
try:
with tarfile.open(archive, "r:gz") as tar:
safe_extract_tar(tar, tmp_dir)
command = self._archive_runtime_command(tmp_dir, node)
if not command:
self._install_reason = "runtime_install_missing_bin"
return self._managed_install_operation_command(
existing_command,
replacement_required=force,
)
versions_dir = self.runtime_dir / "prebuilt" / "versions"
versions_dir.mkdir(parents=True, exist_ok=True)
candidate_dir = Path(
tempfile.mkdtemp(
prefix=f"{archive_digest[:16]}-",
dir=versions_dir,
)
)
candidate_dir.rmdir()
shutil.move(str(tmp_dir), str(candidate_dir))
self._write_archive_manifest(archive_digest, install_dir=candidate_dir)
installed_command = self._archive_runtime_command(candidate_dir, node)
if not installed_command:
self._install_reason = "runtime_install_missing_bin"
return self._managed_install_operation_command(
existing_command,
replacement_required=force,
)
if candidate_validator is not None:
validation = candidate_validator(installed_command)
if validation.state is not ShowRuntimeStartabilityState.STARTABLE:
self._install_reason = self._startability_failure_reason(validation)
return self._managed_install_operation_command(
existing_command,
replacement_required=force,
)
reference_key = self._install_reference_key(candidate_dir)
already_owned = bool(
reference_key is not None
and self._owns_install_reference(reference_key)
)
if not self._retain_managed_command(installed_command):
self._install_reason = self._install_reason or "runtime_install_guard_unavailable"
return self._managed_install_operation_command(
existing_command,
replacement_required=force,
)
if reference_key is not None and not already_owned:
retained_publication_key = reference_key
self._write_provider_pointer(
self.runtime_dir / "prebuilt",
candidate_dir,
provider=_RUNTIME_SOURCE_ARCHIVE,
)
candidate_dir = None
return self._managed_install_operation_command(
installed_command,
replacement_required=force,
replacement_completed=force and installed_command is not None,
)
except Exception:
logger.exception("Failed to install prebuilt Show Runtime")
self._install_reason = "runtime_install_failed"
return self._managed_install_operation_command(
existing_command,
replacement_required=force,
)
finally:
if candidate_dir is not None:
if retained_publication_key is not None:
self._release_install_reference(retained_publication_key)
shutil.rmtree(candidate_dir, ignore_errors=True)
if tmp_dir.exists():
shutil.rmtree(tmp_dir, ignore_errors=True)
def _resolve_prebuilt_archive(self, *, offline: bool | None = None) -> Path | None:
if self.archive_path:
if self.archive_path.exists():
return self.archive_path
self._record_install_failure("runtime_archive_missing", provenance="configured")
return None
packaged = self._copy_packaged_runtime_archive()
if packaged:
return packaged
if not self.archive_url:
self._record_install_failure("runtime_archive_missing", provenance="packaged")
return None
if self.offline if offline is None else offline:
self._install_reason = "runtime_archive_unavailable_offline"
return None
return self._download_runtime_archive(
self.archive_url,
provenance=self._archive_url_provenance,
)
def _copy_packaged_runtime_archive(self) -> Path | None:
try:
resource = package_resources.files("vibe").joinpath("show_runtime", _runtime_archive_name())
except Exception:
return None
if not resource.is_file():
return None
target = self.runtime_dir / "downloads" / _runtime_archive_name()
target.parent.mkdir(parents=True, exist_ok=True)
with resource.open("rb") as source, target.open("wb") as destination:
shutil.copyfileobj(source, destination)
return target
def _download_runtime_archive(self, archive_url: str, *, provenance: str) -> Path | None:
target = self.runtime_dir / "downloads" / _runtime_archive_name()
target.parent.mkdir(parents=True, exist_ok=True)
try:
fetch_to_path(
archive_url,
target,
timeout=60,
opener=urllib.request.urlopen,
)
self._download_error = None
except Exception as exc:
logger.exception("Failed to download prebuilt Show Runtime from %s", archive_url)
self._record_download_failure(
"runtime_archive_download_failed",
exc,
archive_url,
provenance=provenance,
)
return None
return target
def _archive_install_dir(self) -> Path:
return self._selected_provider_install_dir(
self.runtime_dir / "prebuilt",
legacy=self.runtime_dir / "prebuilt" / "current",
provider=_RUNTIME_SOURCE_ARCHIVE,
)
def _archive_manifest_path(self, install_dir: Path | None = None) -> Path:
return (install_dir or self._archive_install_dir()) / ".vibe-show-runtime.json"
def _archive_manifest_matches(
self,
archive_digest: str,
*,
install_dir: Path | None = None,
) -> bool:
try:
payload = json.loads(
self._archive_manifest_path(install_dir).read_text(encoding="utf-8")
)
except Exception:
return False
return payload.get("archive_name") == _runtime_archive_name() and payload.get("sha256") == archive_digest
def _write_archive_manifest(self, archive_digest: str, *, install_dir: Path) -> None:
write_atomic(
self._archive_manifest_path(install_dir),
json.dumps(
{
"provider": _RUNTIME_SOURCE_ARCHIVE,
"runtime_id": "show-runtime",
"archive_name": _runtime_archive_name(),
"sha256": archive_digest,
},
sort_keys=True,
)
+ "\n",
)
def _archive_runtime_command(self, install_dir: Path, node: list[str]) -> list[str] | None:
cli_path = install_dir / "node_modules" / "@avibe" / "show-runtime" / "dist" / "cli.js"
if not cli_path.exists():
return None
return [*node, str(cli_path)]
def _install_npm_runtime(
self,
*,
force: bool | None = None,
candidate_validator: Callable[[list[str]], ShowRuntimeStartability] | None = None,
) -> list[str] | None:
replacement_required = self.force_install if force is None else force
try:
npm = _resolve_command("npm")
except (OSError, ValueError):
npm = None
if not npm:
self._install_reason = "runtime_npm_missing"
return self._managed_install_operation_command(
None,
replacement_required=replacement_required,
)
self.runtime_dir.mkdir(parents=True, exist_ok=True)
existing_command_value = _resolve_executable_path(self._managed_bin_path())
existing_command = [existing_command_value] if existing_command_value else None
if existing_command and not self._retain_managed_command(existing_command):
existing_command = None
staging_root = Path(tempfile.mkdtemp(prefix="npm-", dir=self.runtime_dir))
package_json = staging_root / "package.json"
package_json.write_text('{"private":true,"type":"module"}\n', encoding="utf-8")
candidate_dir: Path | None = None
retained_publication_key: tuple[str, str] | None = None
try:
with self.install_log_path.open("w", encoding="utf-8") as log:
result = subprocess.run(
[
*npm,
"install",
"--prefix",
str(staging_root),
"--no-audit",
"--no-fund",
self.package_spec,
],
stdout=log,
stderr=subprocess.STDOUT,
text=True,
timeout=180,
check=False,
**isolated_subprocess_kwargs(),
)
except (OSError, subprocess.SubprocessError):
logger.warning("Failed to install the npm Show Runtime", exc_info=True)
self._install_reason = "runtime_install_failed"
shutil.rmtree(staging_root, ignore_errors=True)
return self._managed_install_operation_command(
existing_command,
replacement_required=replacement_required,
)
if result.returncode != 0:
self._install_reason = "runtime_install_failed"
shutil.rmtree(staging_root, ignore_errors=True)
return self._managed_install_operation_command(
existing_command,
replacement_required=replacement_required,
)
try:
resolved = _resolve_executable_path(self._npm_bin_path(staging_root))
if not resolved:
self._install_reason = "runtime_install_missing_bin"
return self._managed_install_operation_command(
existing_command,
replacement_required=replacement_required,
)
versions_dir = self.runtime_dir / "package" / "versions"
versions_dir.mkdir(parents=True, exist_ok=True)
candidate_dir = Path(tempfile.mkdtemp(prefix="npm-", dir=versions_dir))
candidate_dir.rmdir()
shutil.move(str(staging_root), str(candidate_dir))
installed_value = _resolve_executable_path(self._npm_bin_path(candidate_dir))
if not installed_value:
self._install_reason = "runtime_install_missing_bin"
return self._managed_install_operation_command(
existing_command,
replacement_required=replacement_required,
)
installed_command = [installed_value]
write_atomic(
candidate_dir / ".vibe-show-runtime.json",
json.dumps(
{
"provider": _RUNTIME_SOURCE_NPM,
"runtime_id": "show-runtime",
"package_spec": self.package_spec,
},
sort_keys=True,
)
+ "\n",
)
if candidate_validator is not None:
validation = candidate_validator(installed_command)
if validation.state is not ShowRuntimeStartabilityState.STARTABLE:
self._install_reason = self._startability_failure_reason(validation)
return self._managed_install_operation_command(
existing_command,
replacement_required=replacement_required,
)
reference_key = self._install_reference_key(candidate_dir)
already_owned = bool(
reference_key is not None
and self._owns_install_reference(reference_key)
)
if not self._retain_managed_command(installed_command):
self._install_reason = self._install_reason or "runtime_install_guard_unavailable"
return self._managed_install_operation_command(
existing_command,
replacement_required=replacement_required,
)
if reference_key is not None and not already_owned:
retained_publication_key = reference_key
self._write_provider_pointer(
self.runtime_dir / "package",
candidate_dir,
provider=_RUNTIME_SOURCE_NPM,
)
candidate_dir = None
return self._managed_install_operation_command(
installed_command,
replacement_required=replacement_required,
replacement_completed=replacement_required,
)
finally:
if candidate_dir is not None:
if retained_publication_key is not None:
self._release_install_reference(retained_publication_key)
shutil.rmtree(candidate_dir, ignore_errors=True)
if staging_root.exists():
shutil.rmtree(staging_root, ignore_errors=True)
def _managed_bin_path(self) -> Path:
return self._npm_bin_path(self._package_install_dir())
def _package_install_dir(self) -> Path:
return self._selected_provider_install_dir(
self.runtime_dir / "package",
legacy=self.runtime_dir / "package",
provider=_RUNTIME_SOURCE_NPM,
)
@staticmethod
def _npm_bin_path(install_dir: Path) -> Path:
suffix = ".cmd" if os.name == "nt" else ""
return install_dir / "node_modules" / ".bin" / f"{_RUNTIME_BIN}{suffix}"
@staticmethod
def _startability_failure_reason(validation: ShowRuntimeStartability) -> str:
if validation.state is ShowRuntimeStartabilityState.NOT_STARTABLE:
return validation.reason or "runtime_start_failed"
return "runtime_start_verification_failed"
def _selected_provider_install_dir(
self,
namespace: Path,
*,
legacy: Path,
provider: str,
) -> Path:
pointer_path = namespace / "current.json"
try:
payload = json.loads(pointer_path.read_text(encoding="utf-8"))
except FileNotFoundError:
return legacy
except (OSError, UnicodeError, ValueError) as exc:
raise OSError(f"runtime pointer is unreadable: {pointer_path}") from exc
try:
install_dir = Path(payload["install_dir"]).expanduser().resolve(strict=True)
versions_dir = (namespace / "versions").resolve(strict=True)
except (KeyError, OSError, RuntimeError, TypeError) as exc:
raise OSError(f"runtime pointer is unreadable: {pointer_path}") from exc
if payload.get("provider") != provider or install_dir.parent != versions_dir:
raise OSError(f"runtime pointer is not confined: {pointer_path}")
return install_dir
@staticmethod
def _write_provider_pointer(namespace: Path, install_dir: Path, *, provider: str) -> None:
write_atomic(
namespace / "current.json",
json.dumps(
{
"provider": provider,
"runtime_id": "show-runtime",
"install_dir": str(install_dir),
},
sort_keys=True,
)
+ "\n",
)
_manager: ShowRuntimeManager | None = None
_manager_lock = threading.Lock()
def get_show_runtime_manager() -> ShowRuntimeManager:
global _manager
if _manager is None:
with _manager_lock:
if _manager is None:
_manager = ShowRuntimeManager()
return _manager
def stop_show_runtime_manager() -> None:
with _manager_lock:
manager = _manager
if manager is not None:
manager.stop()
def _is_runtime_server_cmdline(cmdline: list[str], workspace_root: str) -> bool:
"""True if ``cmdline`` is a Show Runtime server bound to ``workspace_root``.
Requires the exact ``--workspace-root <workspace_root>`` arg pair AND a runtime
signature (the always-present ``--fallback-delay-seconds`` flag, the ``cli.js``
entrypoint, the managed bin, or a ``show-runtime`` path token), so an unrelated
process that merely mentions the path is never matched.
"""
if not cmdline:
return False
bound = any(
token == "--workspace-root" and index + 1 < len(cmdline) and cmdline[index + 1] == workspace_root
for index, token in enumerate(cmdline)
)
if not bound:
return False
return any(
token == "--fallback-delay-seconds"
or token.endswith("cli.js")
or token.endswith(_RUNTIME_BIN)
or "show-runtime" in token
for token in cmdline
)
def sweep_orphan_show_runtime_servers(
workspace_root: Path | str | None = None,
*,
keep_pid: int | None = None,
) -> list[int]:
"""Terminate any Show Runtime server still bound to ``workspace_root``.
A prior avibe instance that died without reaping its child (SIGKILL / crash —
``atexit`` does not run) leaves a Node ``cli.js`` orphan reparented to init, still
listening on its old port and able to warm/mutate this workspace root with stale
in-memory templates (avibe-bot/avibe#813). The single-service-instance lock makes
this process the only legitimate owner of the root, so any *other* process bound to
it is an orphan and safe to reap.
Best-effort and spawn-agnostic: complements the runtime's own parent-death self-exit
(vibe-show-runtime#30) by also clearing orphans from builds that predate that
backstop. Returns the pids swept (for logging/tests).
"""
root = str(workspace_root) if workspace_root is not None else str(paths.get_show_pages_dir())
try:
import psutil
except Exception: # pragma: no cover - psutil is a hard dependency in practice
return []
own_pid = os.getpid()
swept: list[int] = []
for proc in psutil.process_iter(["pid", "cmdline"]):
try:
pid = proc.info.get("pid")
if pid is None or pid == own_pid or (keep_pid is not None and pid == keep_pid):
continue
if not _is_runtime_server_cmdline(proc.info.get("cmdline") or [], root):
continue
victims = proc.children(recursive=True)
except (psutil.NoSuchProcess, psutil.AccessDenied):
continue
except Exception: # pragma: no cover - never let a stray psutil error block callers
logger.debug("Failed to inspect process while sweeping show runtime orphans", exc_info=True)
continue
victims.append(proc)
logger.warning(
"Sweeping orphaned show runtime server pid=%s bound to workspace_root=%s", pid, root
)
for victim in victims:
try:
victim.terminate()
except (psutil.NoSuchProcess, psutil.AccessDenied):
continue
_gone, alive = psutil.wait_procs(victims, timeout=3)
for victim in alive:
try:
victim.kill()
except (psutil.NoSuchProcess, psutil.AccessDenied):
continue
swept.append(pid)
return swept
async def prewarm_show_runtime() -> ShowRuntimeAvailability:
return await get_show_runtime_manager().ensure()
async def prewarm_show_page_session(
session_id: str,
*,
context: ShowRuntimeContext,
) -> ShowRuntimeResult:
return await get_show_runtime_manager().prewarm_session(
session_id,
context=context,
)
def _show_runtime_app_session_part(path: str) -> str | None:
match = re.match(r"^/sessions/([^/]+)/app(?:/|$)", path)
return match.group(1) if match else None
def set_show_runtime_manager_for_tests(manager: ShowRuntimeManager | None) -> None:
global _manager
with _manager_lock:
previous = _manager
_manager = manager
# Stop the manager we are replacing before dropping the reference. Serving-path
# tests that never install a fake cause get_show_runtime_manager() to lazily
# create the real manager, which spawns a Node cli.js + esbuild subprocess tree
# when a runtime is installed locally. If a later test swaps the global without
# stopping it first, the reference is lost, the atexit cleanup at process exit
# can no longer reap it, and the subprocess tree leaks for the machine's lifetime.
if previous is not None and previous is not manager:
try:
previous.stop()
except Exception: # pragma: no cover - defensive cleanup
logger.debug("failed to stop previous show runtime manager", exc_info=True)
def _show_runtime_prewarm_import_paths(
response: httpx.Response,
*,
session_id: str,
runtime_path: str,
base_path: str | None,
) -> list[str]:
content_type = response.headers.get("content-type", "")
if "javascript" not in content_type and "html" not in content_type and "css" not in content_type:
return []
try:
text = response.text
except UnicodeDecodeError:
return []
paths: list[str] = []
seen: set[str] = set()
for match in _PREWARM_IMPORT_RE.finditer(text):
value = match.group("path")
path = _show_runtime_prewarm_runtime_path(
value,
session_id=session_id,
runtime_path=runtime_path,
base_path=base_path,
)
if path and path not in seen:
seen.add(path)
paths.append(path)
return paths
def _show_runtime_prewarm_runtime_path(
value: str,
*,
session_id: str,
runtime_path: str,
base_path: str | None,
) -> str | None:
if not value or value.startswith(("http://", "https://", "data:", "blob:", "#")):
return None
raw_path, separator, query = value.partition("?")
if not _show_runtime_prewarm_asset_path_allowed(raw_path):
return None
session_prefixes = [f"/show/{session_id}/", f"/p/{session_id}/"]
if base_path:
session_prefixes.insert(0, base_path.rstrip("/") + "/")
for prefix in session_prefixes:
if raw_path.startswith(prefix):
asset_path = raw_path[len(prefix):]
return _join_show_runtime_prewarm_path(runtime_path, asset_path, separator, query)
# The shared vendor bundle (`/_show-runtime/vendor/...`) is session-independent and
# the runtime warms it itself, so it is intentionally not prewarmed per session here.
if raw_path.startswith("/src/") or raw_path.startswith("/@") or raw_path.startswith("/node_modules/"):
return _join_show_runtime_prewarm_path(runtime_path, raw_path.lstrip("/"), separator, query)
if raw_path.startswith("./"):
return _join_show_runtime_prewarm_path(runtime_path, raw_path[2:], separator, query)
if raw_path.startswith(("src/", "@", "node_modules/")):
return _join_show_runtime_prewarm_path(runtime_path, raw_path, separator, query)
return None
def _show_runtime_prewarm_asset_path_allowed(path: str) -> bool:
if not path:
return False
if path.startswith(("/home/", "/Users/", "/tmp/", "/var/", "/private/")):
return False
return path.endswith((".js", ".mjs", ".ts", ".tsx", ".css")) or path in {
"/@vite/client",
"/@react-refresh",
}
def _join_show_runtime_prewarm_path(runtime_path: str, asset_path: str, separator: str, query: str) -> str:
path = f"{runtime_path}{urllib.parse.quote(asset_path.lstrip('/'), safe='/@:-._~')}"
if separator:
path = f"{path}?{query}"
return path
def _show_runtime_capability_retry_delay(attempt: int) -> float:
exponent = max(0, min(attempt - 1, 16))
ceiling = min(_CAPABILITY_RETRY_MAX_SECONDS, _CAPABILITY_RETRY_BASE_SECONDS * (2**exponent))
return ceiling * (0.5 + random.random() * 0.5)
def _auto_install_enabled() -> bool:
value = os.environ.get("VIBE_SHOW_RUNTIME_AUTO_INSTALL")
return value is None or value.strip().lower() not in _FALSE_VALUES
def _packaged_runtime_manifest_exists() -> bool:
try:
resource = package_resources.files("vibe").joinpath(_RUNTIME_MANIFEST_RESOURCE)
except Exception:
return False
return resource.is_file()
def _normalize_runtime_source(value: str | None) -> str:
retired_source = retired_show_runtime_source(value)
normalized = retired_source or (value or _RUNTIME_SOURCE_MANIFEST).strip().lower()
aliases = {
"manifest": _RUNTIME_SOURCE_MANIFEST,
"manifest-cache": _RUNTIME_SOURCE_MANIFEST,
"archive": _RUNTIME_SOURCE_ARCHIVE,
"prebuilt": _RUNTIME_SOURCE_ARCHIVE,
"npm": _RUNTIME_SOURCE_NPM,
}
if retired_source is not None and retired_source not in _WARNED_RETIRED_RUNTIME_SOURCES:
_WARNED_RETIRED_RUNTIME_SOURCES.add(retired_source)
logger.warning(
"VIBE_SHOW_RUNTIME_SOURCE=%s is retired; using %s instead",
retired_source,
_RUNTIME_SOURCE_MANIFEST,
)
if retired_source is not None:
return _RUNTIME_SOURCE_MANIFEST
return aliases.get(normalized, normalized or _RUNTIME_SOURCE_MANIFEST)
def _manifest_status_payload(manifest: ManagedRuntimeManifest | None) -> dict[str, Any] | None:
if manifest is None:
return None
return {
"schema_version": manifest.schema_version,
"runtime_version": manifest.runtime_version,
"minimum_node": _ShowManifestRuntimeManager._minimum_node(manifest),
"sha256": manifest.digest,
"source": manifest.loaded_from,
"platforms": sorted(manifest.archives),
}
def _persisted_manifest_status_payload(metadata: Mapping[str, Any]) -> dict[str, Any]:
return {
"schema_version": None,
"runtime_version": metadata.get("runtime_version"),
"minimum_node": None,
"sha256": metadata.get("manifest_sha256"),
"source": metadata.get("manifest_source"),
"platforms": [metadata.get("platform")],
}
def _persisted_manifest_runtime_version(metadata: Mapping[str, Any]) -> str | None:
runtime_version = metadata.get("runtime_version")
return runtime_version if isinstance(runtime_version, str) and runtime_version else None
def _persisted_archive_status_payload(metadata: Mapping[str, Any]) -> dict[str, Any]:
return {
"platform": metadata.get("platform"),
"name": metadata.get("archive_name"),
"url": None,
"sha256": metadata.get("archive_sha256"),
"size": None,
}
def _redact_download_url(url: str) -> str:
return redact_url(url)
def _runtime_download_error(exc: BaseException, url: str) -> dict[str, Any]:
return dependency_error_details(exc, url)
def _archive_status_payload(archive: ManagedRuntimeArchive | None) -> dict[str, Any] | None:
if archive is None:
return None
return {
"platform": archive.platform,
"name": archive.name,
"url": _redact_download_url(archive.url),
"sha256": archive.sha256,
"size": archive.size,
}
def _runtime_archive_name() -> str:
return f"{_RUNTIME_ARCHIVE_PREFIX}-{runtime_platform_tag()}.tgz"
def _default_runtime_archive_url() -> str:
return f"{_RUNTIME_ARCHIVE_RELEASE_BASE_URL}/{_runtime_archive_name()}"
def _node_version(node: list[str]) -> tuple[int, int, int] | None:
try:
result = subprocess.run(
[*node, "--version"],
capture_output=True,
text=True,
timeout=5,
check=False,
**isolated_subprocess_kwargs(),
)
except Exception:
return None
if result.returncode != 0:
return None
return _parse_semver(result.stdout.strip())
def _parse_semver(value: str) -> tuple[int, int, int] | None:
match = re.search(r"v?(\d+)\.(\d+)\.(\d+)", value)
if not match:
return None
return int(match.group(1)), int(match.group(2)), int(match.group(3))
def _format_semver(version: tuple[int, int, int] | None) -> str | None:
if version is None:
return None
return ".".join(str(part) for part in version)
def _node_satisfies_requirement(version: tuple[int, int, int] | None, requirement: str | None) -> bool | None:
if not requirement:
return None
if version is None:
return False
return any(_node_satisfies_clause(version, clause.strip()) for clause in requirement.split("||") if clause.strip())
def _node_satisfies_clause(version: tuple[int, int, int], clause: str) -> bool:
if clause.startswith(">="):
minimum = _parse_semver(clause[2:].strip())
return minimum is not None and version >= minimum
if clause.startswith("^"):
minimum = _parse_semver(clause[1:].strip())
if minimum is None or version < minimum:
return False
major, minor, patch = minimum
if major > 0:
ceiling = (major + 1, 0, 0)
elif minor > 0:
ceiling = (major, minor + 1, 0)
else:
ceiling = (major, minor, patch + 1)
return version < ceiling
exact = _parse_semver(clause)
return exact is not None and version == exact
def _resolve_command(command: str) -> list[str] | None:
parts = shlex.split(command)
if not parts:
return None
executable = parts[0]
if os.path.sep in executable or (os.altsep is not None and os.altsep in executable):
path = Path(executable).expanduser()
resolved = str(path) if path.exists() and os.access(path, os.X_OK) else None
else:
resolved = shutil.which(executable)
if not resolved:
return None
return [resolved, *parts[1:]]
def _resolve_node_command() -> list[str] | None:
configured = os.environ.get("VIBE_SHOW_RUNTIME_NODE_BIN")
try:
if configured:
resolved = _resolve_executable_path(Path(configured))
return [resolved] if resolved else None
return _resolve_command("node")
except (OSError, ValueError):
return None
def _resolve_executable_path(path: Path) -> str | None:
expanded = path.expanduser()
return str(expanded) if expanded.exists() and os.access(expanded, os.X_OK) else None
atexit.register(stop_show_runtime_manager)