From 63b7a5ee5ef94b31e1504bb07680760881aed774 Mon Sep 17 00:00:00 2001 From: Reinier Criel Date: Mon, 13 Apr 2026 21:40:53 -0700 Subject: [PATCH] Add better doc --- install-scripts/install-safe-chain.ps1 | 8 ++++++++ install-scripts/install-safe-chain.sh | 9 +++++++++ install-scripts/uninstall-safe-chain.ps1 | 14 ++++++++++++++ install-scripts/uninstall-safe-chain.sh | 16 ++++++++++++++++ 4 files changed, 47 insertions(+) diff --git a/install-scripts/install-safe-chain.ps1 b/install-scripts/install-safe-chain.ps1 index f870123..0d7b745 100644 --- a/install-scripts/install-safe-chain.ps1 +++ b/install-scripts/install-safe-chain.ps1 @@ -8,6 +8,8 @@ param( [string]$InstallDir ) +# Validates and normalizes the requested install directory. +# Rejects non-absolute, root, PATH-like, and traversal-containing paths. function Test-InstallDir { param([string]$Dir) @@ -137,6 +139,8 @@ function Get-Architecture { } } +# Emits the deprecation warning for SAFE_CHAIN_VERSION and prints the version-pinned install command. +# Returns immediately when no version was provided through the environment. function Write-VersionDeprecationWarning { if ([string]::IsNullOrWhiteSpace($env:SAFE_CHAIN_VERSION)) { return @@ -154,12 +158,16 @@ function Write-VersionDeprecationWarning { Write-Warn "" } +# Builds the Windows release binary filename for the detected architecture. +# Centralizes binary name generation for the download step. function Get-BinaryName { param([string]$Architecture) return "safe-chain-win-$Architecture.exe" } +# Runs safe-chain setup or setup-ci after the binary is installed. +# Temporarily appends the install directory to PATH and downgrades setup failures to warnings. function Invoke-SafeChainSetup { param( [string]$BinaryPath, diff --git a/install-scripts/install-safe-chain.sh b/install-scripts/install-safe-chain.sh index 2335ae3..763dab6 100755 --- a/install-scripts/install-safe-chain.sh +++ b/install-scripts/install-safe-chain.sh @@ -6,6 +6,8 @@ set -e # Exit on error +# Validates a user-provided install dir and exits on unsafe values. +# Rejects relative paths, root paths, PATH separators, and traversal segments. validate_install_dir() { dir="$1" @@ -168,6 +170,8 @@ download() { fi } +# Prints the deprecation warning for SAFE_CHAIN_VERSION and the replacement install command. +# Returns immediately when no version was pinned through the environment. warn_deprecated_version_env() { if [ -z "$SAFE_CHAIN_VERSION" ]; then return @@ -185,6 +189,8 @@ warn_deprecated_version_env() { warn "" } +# Ensures VERSION is populated before installation continues. +# Fetches the latest release only when no explicit version was provided. ensure_version() { if [ -n "$VERSION" ]; then return @@ -194,6 +200,7 @@ ensure_version() { VERSION=$(fetch_latest_version) } +# Returns the release binary filename for the detected OS and architecture. get_binary_name() { os="$1" arch="$2" @@ -205,6 +212,8 @@ get_binary_name() { fi } +# Returns the final installation path for the downloaded safe-chain binary. +# Uses INSTALL_DIR and the platform-specific executable name. get_final_binary_path() { os="$1" diff --git a/install-scripts/uninstall-safe-chain.ps1 b/install-scripts/uninstall-safe-chain.ps1 index 1304247..6e24d5d 100644 --- a/install-scripts/uninstall-safe-chain.ps1 +++ b/install-scripts/uninstall-safe-chain.ps1 @@ -22,6 +22,8 @@ function Write-Error-Custom { exit 1 } +# Derives the safe-chain base install directory from a resolved binary path. +# Rejects wrapper scripts and paths that do not match the packaged bin layout. function Get-InstallDirFromBinaryPath { param([string]$BinaryPath) @@ -53,10 +55,14 @@ function Get-InstallDirFromBinaryPath { return (Split-Path -Parent $binDir) } +# Returns the first safe-chain command found on PATH, if any. +# Used as the starting point for install-dir discovery. function Get-SafeChainCommand { return Get-Command safe-chain -ErrorAction SilentlyContinue | Select-Object -First 1 } +# Returns the safe-chain command path only when it points to a valid packaged binary install. +# Prevents teardown from invoking arbitrary wrappers or scripts from PATH. function Get-ValidatedSafeChainCommandPath { $command = Get-SafeChainCommand if (-not $command -or [string]::IsNullOrWhiteSpace($command.Path)) { @@ -71,6 +77,8 @@ function Get-ValidatedSafeChainCommandPath { return $command.Path } +# Invokes the validated safe-chain binary with get-install-dir and returns the reported base directory. +# Safely returns $null when the command is unavailable or the lookup fails. function Get-ReportedInstallDir { $safeChainPath = Get-ValidatedSafeChainCommandPath if (-not $safeChainPath) { @@ -93,6 +101,8 @@ function Get-ReportedInstallDir { return $null } +# Determines the safe-chain base install directory for uninstall. +# Prefers the binary-reported location, then derives it from PATH, then falls back to the default home-dir layout. function Get-SafeChainInstallDir { $reportedInstallDir = Get-ReportedInstallDir if ($reportedInstallDir) { @@ -110,6 +120,8 @@ function Get-SafeChainInstallDir { return (Join-Path $HomeDir ".safe-chain") } +# Finds the installed safe-chain binary inside the resolved install directory. +# Falls back to a validated safe-chain command when the expected file is missing. function Find-SafeChainBinary { param([string]$DotSafeChain) @@ -127,6 +139,8 @@ function Find-SafeChainBinary { return Get-ValidatedSafeChainCommandPath } +# Runs safe-chain teardown before removing the installation directory. +# Converts teardown failures into warnings so uninstall can still complete. function Invoke-SafeChainTeardown { param([string]$SafeChainPath) diff --git a/install-scripts/uninstall-safe-chain.sh b/install-scripts/uninstall-safe-chain.sh index 7a7cb7d..abe235f 100755 --- a/install-scripts/uninstall-safe-chain.sh +++ b/install-scripts/uninstall-safe-chain.sh @@ -33,6 +33,8 @@ command_exists() { command -v "$1" >/dev/null 2>&1 } +# Resolves a path to its canonical filesystem location when possible. +# Follows symlinks so binary validation can inspect the real installed path. resolve_path() { target="$1" @@ -60,6 +62,8 @@ resolve_path() { fi } +# Derives the safe-chain base install directory from a packaged binary path. +# Rejects wrapper scripts and paths that do not match the expected bin layout. derive_install_dir_from_binary() { binary_path="$1" @@ -86,6 +90,8 @@ derive_install_dir_from_binary() { dirname "$binary_dir" } +# Determines the installed safe-chain base directory for uninstall. +# Prefers the binary-reported location, then infers it from PATH, then falls back to ~/.safe-chain. get_install_dir() { reported_install_dir=$(get_reported_install_dir) if [ -n "$reported_install_dir" ]; then @@ -103,6 +109,8 @@ get_install_dir() { printf '%s\n' "${HOME}/.safe-chain" } +# Returns the current safe-chain command path from PATH. +# Fails when safe-chain is not currently resolvable. get_safe_chain_command_path() { if ! command_exists safe-chain; then return 1 @@ -111,6 +119,8 @@ get_safe_chain_command_path() { command -v safe-chain } +# Returns the safe-chain command path only when it resolves to a valid packaged binary install. +# Prevents the uninstaller from invoking arbitrary PATH entries. get_validated_safe_chain_command_path() { command_path=$(get_safe_chain_command_path || true) if [ -z "$command_path" ]; then @@ -125,6 +135,8 @@ get_validated_safe_chain_command_path() { printf '%s\n' "$command_path" } +# Asks the validated safe-chain binary for its install directory via get-install-dir. +# Returns nothing if the command is unavailable or the lookup fails. get_reported_install_dir() { safe_chain_path=$(get_validated_safe_chain_command_path || true) if [ -z "$safe_chain_path" ]; then @@ -140,6 +152,8 @@ get_reported_install_dir() { return 1 } +# Locates the installed safe-chain binary to use for teardown. +# Checks the discovered install dir first, then falls back to a validated PATH entry. find_installed_safe_chain_binary() { dot_safe_chain="$1" @@ -158,6 +172,8 @@ find_installed_safe_chain_binary() { return 1 } +# Runs safe-chain teardown before removing files. +# Continues with uninstall even if teardown is unavailable or fails. run_safe_chain_teardown() { safe_chain_command="$1"