utils/native_installer/native_installer library
Native Installer Implementation
Faithful port of neomage/src/utils/nativeInstaller/*.ts Covers: installer.ts, download.ts, pidLock.ts, packageManagers.ts
Provides:
- Directory structure management with symlinks
- Version installation and activation
- Multi-process safety with PID-based and mtime-based locking
- Binary download with checksum verification, stall detection, retry
- Package manager detection (homebrew, winget, pacman, deb, rpm, apk, mise, asdf)
Classes
- LockInfo
- Diagnostic lock information.
- NativeInstallerController
- Manages the native installer lifecycle using Sint state management.
- OsReleaseInfo
- Parsed /etc/os-release fields.
- SetupMessage
- A message generated during the setup/installation process.
- VersionLockContent
- Content stored in a version lock file.
Enums
- PackageManager
- Supported package manager types.
- SetupMessageType
- Types of setup messages displayed during installation.
Constants
- artifactoryRegistryUrl → const String
- Artifactory npm registry URL for internal binary downloads.
- defaultStallTimeoutMs → const int
- Stall timeout: abort if no bytes received for this duration.
- fallbackStaleMs → const int
- Fallback stale timeout (2 hours) for PID-based locks when PID check is inconclusive.
- gcsBucketUrl → const String
- GCS bucket URL for external binary downloads.
- lockStaleMs → const int
- 7 days in milliseconds — mtime-based lock stale timeout. Long enough to survive laptop sleep, short enough for eventual cleanup.
- maxDownloadRetries → const int
- Maximum download retries on stall timeout.
- versionRetentionCount → const int
- Number of old versions to retain before cleanup.
Functions
-
acquireProcessLifetimeLock(
String versionPath, String lockFilePath) → Future< bool> - Acquire a lock and hold it for the lifetime of the process.
-
cleanupStaleLocks(
String locksDir) → int - Clean up stale locks (locks where the process is no longer running). Returns the number of locks cleaned up. Handles both PID-based locks and legacy directory locks.
-
detectApk(
) → Future< bool> - Detects if installed via Alpine APK by querying apk.
-
detectAsdf(
) → bool -
Detects if the currently running instance was installed via asdf.
asdf installs to:
~/.asdf/installs/<tool>/<version>/ -
detectDeb(
) → Future< bool> - Detects if installed via a .deb package by querying dpkg.
-
detectHomebrew(
) → bool - Detects if the currently running instance was installed via Homebrew. Checks for Caskroom path specifically to distinguish from npm-global via Homebrew's npm.
-
detectMise(
) → bool -
Detects if the currently running instance was installed via mise.
mise installs to:
~/.local/share/mise/installs/<tool>/<version>/ -
detectPacman(
) → Future< bool> - Detects if installed via pacman by querying pacman's database. Gates on Arch distro family before invoking pacman.
-
detectRpm(
) → Future< bool> - Detects if installed via an RPM package by querying rpm.
-
detectWinget(
) → bool - Detects if the currently running instance was installed via winget. Winget installs to %LOCALAPPDATA%\Microsoft\WinGet\Packages or C:\Program Files\WinGet\Packages.
-
downloadAndVerifyBinary(
{required String binaryUrl, required String expectedChecksum, required String binaryPath, String? authUsername, String? authPassword}) → Future< void> - Download and verify a binary with stall detection and retry logic.
-
downloadVersion(
String version, String stagingPath) → Future< String> - Download a version, routing to appropriate source. Returns the download type ('npm' or 'binary').
-
downloadVersionFromBinaryRepo(
{required String version, required String stagingPath, required String baseUrl, String? authUsername, String? authPassword}) → Future< void> - Download a version from a binary repository.
-
getAllLockInfo(
String locksDir) → List< LockInfo> - Get information about all version locks for diagnostics.
-
getBinaryName(
String platform) → String - Get the binary name for the platform.
-
getLatestVersion(
String channelOrVersion) → Future< String> - Get the latest version, either from direct version string or channel lookup.
-
getLatestVersionFromBinaryRepo(
{String channel = 'latest', required String baseUrl, String? authUsername, String? authPassword}) → Future< String> - Get the latest version from a binary repo channel endpoint.
-
getOsRelease(
) → Future< OsReleaseInfo?> - Parses /etc/os-release to extract the distro ID and ID_LIKE fields. ID_LIKE identifies the distro family (e.g. Ubuntu has ID_LIKE=debian). Returns null if the file is unreadable.
-
getPackageManager(
) → Future< PackageManager> - Detect which package manager installed the application. Returns PackageManager.unknown if none detected.
-
getPlatform(
) → String - Get the platform string for binary downloads (e.g., "darwin-arm64").
-
getStallTimeoutMs(
) → int - Get the stall timeout in milliseconds, checking env override first.
-
isDistroFamily(
OsReleaseInfo osRelease, List< String> families) → bool - Check if the OS release matches any of the given distro families.
-
isLockActive(
String lockFilePath) → bool - Check if a lock file represents an active lock (process still running).
-
isPidBasedLockingEnabled(
) → bool - Whether PID-based locking is enabled. Controlled by environment variable or feature gate.
-
isProcessRunning(
int pid) → bool - Check if a process with the given PID is currently running. Uses signal 0 which checks permission without sending a signal.
-
readLockContent(
String lockFilePath) → VersionLockContent? - Read and parse a lock file's content.
-
tryAcquireLock(
String versionPath, String lockFilePath) → Future< void Function()?> - Try to acquire a lock on a version file. Returns a release function if successful, null if already held.
-
withLock(
String versionPath, String lockFilePath, Future< void> callback()) → Future<bool> - Execute a callback while holding a lock. Returns true if the callback executed, false if lock couldn't be acquired.
-
writeLockFile(
String lockFilePath, VersionLockContent content) → void - Write lock content to a file atomically.
Exceptions / Errors
- StallTimeoutError
- Error thrown when a download stalls (no data received for timeout period).