Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

feat(installer,web): one canonical bundle per target; robust in-place upgrades; update-check feedback (#142)

Laodouuu84949882ab1e
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 6d1b4e99..2dc06129 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -45,8 +45,8 @@ jobs:
- name: Unit tests (vitest)
run: pnpm test
- - name: Offline bundle and POSIX installer tests
- run: sh scripts/test-offline-bundles.sh
+ - name: Installer bundle and POSIX installer tests
+ run: sh scripts/test-installer.sh
# The secret is exposed only in this step (step-level env); earlier steps and third-party actions can't see it.
# The secrets context can't be used in if expressions, so skip inside the shell when it's absent (e.g. forks).
@@ -112,6 +112,6 @@ jobs:
}
if ($failed) { exit 1 }
- - name: Windows offline installer tests
+ - name: Windows installer tests
shell: pwsh
- run: ./scripts/test-offline-install.ps1
+ run: ./scripts/test-installer.ps1
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index adb15a9c..3c0b3e01 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -4,9 +4,15 @@
# already-released tag skips the build/upload entirely and only re-runs npm publishing.
# Two parallel jobs (the release job is gated on the existence check):
# - release: build the monorepo -> pnpm deploy a production CLI dir -> assemble penguin/ (bin + lib + web)
-# -> five platform packages each bundling the official Node runtime + a universal package -> SHA256 files -> upload to the Release.
-# Artifacts: penguin-{linux,darwin}-{x64,arm64}.tar.gz, penguin-win32-x64.zip, penguin-universal.tar.gz,
-# their .sha256 files, SHA256SUMS, install.sh, and install.ps1; one version per tag, multiple versions coexist.
+# -> one program payload per target (four platform payloads bundling the official Node runtime,
+# a win-x64 payload with runtime + MinGit, and a runtime-less universal payload) -> wrap each
+# payload, its checksum and the native installer into the canonical installer bundle -> validate
+# the real bundles -> upload to the Release.
+# Artifacts (one shape per target, serving online and offline installs alike):
+# penguin-{linux,darwin}-{x64,arm64}.tar.gz, penguin-universal.tar.gz, penguin-win32-x64.zip,
+# their .sha256 files, SHA256SUMS, install.sh, and install.ps1; one version per tag, multiple
+# versions coexist. Releases up to v0.1.5 shipped raw program archives under the same names
+# plus *-offline wrappers; the installers keep accepting that legacy layout for pinned versions.
# - publish-npm: publish the whole chain (@prismshadow/penguin-skills -> @prismshadow/penguin-core
# -> @prismshadow/penguin-server -> @prismshadow/penguin-cli) to npm at the tag version.
# skills/core serve the penguin-sdk Skill's `npm install`; server ships the built web assets inside
@@ -136,11 +142,13 @@ jobs:
EOF
chmod +x out/penguin/bin/penguin
- # Platform packages: linux uses .tar.xz, darwin uses .tar.gz (nodejs.org naming);
- # node/ is only lightly trimmed (drop share/doc and share/man, keep the rest).
- - name: Package platform + universal tarballs
+ # Program payloads: linux runtimes use .tar.xz, darwin .tar.gz (nodejs.org naming);
+ # node/ is only lightly trimmed (drop share/doc and share/man, keep the rest). Payloads
+ # are intermediate files named <target>.tar.gz / win32-x64.zip: the packaging script
+ # below seals each one into the canonical installer bundle that gets published.
+ - name: Package platform + universal payloads
run: |
- mkdir -p dist-artifacts
+ mkdir -p payloads
for target in linux-x64 linux-arm64 darwin-x64 darwin-arm64; do
os="${target%%-*}"
arch="${target#*-}"
@@ -157,19 +165,22 @@ jobs:
mv "/tmp/node-runtime/$name" out/penguin/node
rm -rf out/penguin/node/share/doc out/penguin/node/share/man
printf '{"schemaVersion":1,"target":"%s"}\n' "$os-$arch" > out/penguin/package-manifest.json
- tar -czf "dist-artifacts/penguin-$os-$arch.tar.gz" -C out penguin
+ tar -czf "payloads/$os-$arch.tar.gz" -C out penguin
done
- # Universal package: no bundled runtime, requires system Node >= 24.
+ # Universal payload: no bundled runtime, requires system Node >= 24.
rm -rf out/penguin/node
printf '{"schemaVersion":1,"target":"universal"}\n' > out/penguin/package-manifest.json
- tar -czf dist-artifacts/penguin-universal.tar.gz -C out penguin
+ tar -czf payloads/universal.tar.gz -C out penguin
- # Windows package: same lib/ + web/ layout, but a .zip (the native format), the official
- # win-x64 Node runtime — whose zip has node.exe at the ARCHIVE ROOT, not bin/ — and
- # cmd/ps1 launchers replacing the sh one (resolve their own dir, default PENGUIN_WEB_DIST
- # to the sibling web\, prefer the bundled node\node.exe, fall back to system node).
- # install.ps1 verifies and unpacks this zip; in PowerShell the .ps1 shim wins over .cmd,
- # in cmd.exe only the .cmd is found — both forward all args and the exit code.
+ # Windows payload: same lib/ + web/ layout, but a .zip (the native format), the official
+ # win-x64 Node runtime — whose zip has node.exe at the ARCHIVE ROOT, not bin/ — and a
+ # cmd launcher replacing the sh one (resolves its own dir, defaults PENGUIN_WEB_DIST to
+ # the sibling web\, prefers the bundled node\node.exe, falls back to system node).
+ # Deliberately NO penguin.ps1 launcher: PowerShell prefers .ps1 over .cmd on PATH, and
+ # client Windows defaults to the Restricted execution policy, so shipping one makes the
+ # plain `penguin` command fail with "running scripts is disabled" out of the box. Batch
+ # files are exempt from the policy and both PowerShell and cmd.exe resolve penguin.cmd,
+ # which forwards all args and the exit code.
#
# It also bundles MinGit under git\, so exec_command has a POSIX shell even on a machine
# with no Git for Windows: the shims advertise git\usr\bin\sh.exe as PENGUIN_BUNDLED_SHELL
@@ -177,7 +188,7 @@ jobs:
# MinGit is unpacked with its tree intact — MSYS binaries locate /etc relative to the
# directory holding msys-2.0.dll, so `sh -lc` finds git\etc\profile and gets the usual
# /mingw64/bin:/usr/bin:<inherited Windows PATH>, keeping System32's curl/tar reachable.
- - name: Package win-x64 zip
+ - name: Package win-x64 payload
run: |
name="node-$NODE_RUNTIME_VERSION-win-x64"
curl -fsSL "https://nodejs.org/dist/$NODE_RUNTIME_VERSION/$name.zip" -o "/tmp/$name.zip"
@@ -211,35 +222,59 @@ jobs:
EOF
# cmd.exe is only fully reliable with CRLF batch files.
sed -i 's/$/\r/' out/penguin/bin/penguin.cmd
- cat > out/penguin/bin/penguin.ps1 <<'EOF'
- $dir = Split-Path -Parent $PSScriptRoot
- if (-not $env:PENGUIN_WEB_DIST) { $env:PENGUIN_WEB_DIST = Join-Path $dir "web" }
- $sh = Join-Path $dir "git\usr\bin\sh.exe"
- if (Test-Path $sh) { $env:PENGUIN_BUNDLED_SHELL = $sh }
- $node = Join-Path $dir "node\node.exe"
- if (-not (Test-Path $node)) { $node = "node" }
- & $node (Join-Path $dir "lib\dist\index.js") @args
- exit $LASTEXITCODE
- EOF
- # PowerShell accepts LF, but ship CRLF like the .cmd (and the repo's *.ps1 eol=crlf attribute).
- sed -i 's/$/\r/' out/penguin/bin/penguin.ps1
- (cd out && zip -qr ../dist-artifacts/penguin-win32-x64.zip penguin)
+ (cd out && zip -qr ../payloads/win32-x64.zip penguin)
+
+ # The canonical artifacts: each payload is sealed with its checksum and the native
+ # installer into one flat bundle per target (see scripts/package-release-bundles.sh).
+ - name: Package canonical installer bundles
+ run: sh scripts/package-release-bundles.sh payloads dist-artifacts
- # Per-payload checksums are included inside the offline bundles and are also consumed by
- # the online install.sh / install.ps1 downloads.
- - name: Generate payload SHA256 checksums
+ # Validate the real release outputs, not only the small fixtures used by the script tests.
+ # Every bundle must pass its outer checksum, stay flat with exactly the documented member
+ # set, carry a byte-identical installer and payload, and pass its sealed payload checksum.
+ - name: Validate canonical installer bundles
run: |
- cd dist-artifacts
- for f in *.tar.gz *.zip; do
- sha256sum "$f" > "$f.sha256"
+ set -eu
+ ARTIFACT_DIR="$PWD/dist-artifacts"
+ PAYLOAD_DIR="$PWD/payloads"
+ WORK_DIR="$(mktemp -d)"
+ trap 'rm -rf "$WORK_DIR"' EXIT
+
+ validate_layout() {
+ dir="$1"
+ expected="$2"
+ actual="$(find "$dir" -mindepth 1 -maxdepth 1 -type f -printf '%f\n' | LC_ALL=C sort)"
+ [ -z "$(find "$dir" -mindepth 2 -print -quit)" ]
+ [ "$actual" = "$expected" ]
+ }
+
+ for target in linux-x64 linux-arm64 darwin-x64 darwin-arm64 universal; do
+ bundle="penguin-$target.tar.gz"
+ (cd "$ARTIFACT_DIR" && sha256sum -c "$bundle.sha256")
+ extracted="$WORK_DIR/$target"
+ mkdir -p "$extracted"
+ tar -xzf "$ARTIFACT_DIR/$bundle" -C "$extracted"
+ expected="$(printf '%s\n' install.sh payload.tar.gz payload.tar.gz.sha256 | LC_ALL=C sort)"
+ validate_layout "$extracted" "$expected"
+ [ -x "$extracted/install.sh" ]
+ (cd "$extracted" && sha256sum -c payload.tar.gz.sha256)
+ cmp "$PWD/install.sh" "$extracted/install.sh"
+ cmp "$PAYLOAD_DIR/$target.tar.gz" "$extracted/payload.tar.gz"
done
- # Each offline bundle contains exactly one platform payload, its checksum and the native installer.
- # Users extract once, then run install.sh (Linux/macOS) or double-click install.cmd (Windows).
- - name: Package offline installer bundles
- run: sh scripts/package-offline-bundles.sh dist-artifacts
+ bundle="penguin-win32-x64.zip"
+ (cd "$ARTIFACT_DIR" && sha256sum -c "$bundle.sha256")
+ extracted="$WORK_DIR/win32-x64"
+ mkdir -p "$extracted"
+ unzip -q "$ARTIFACT_DIR/$bundle" -d "$extracted"
+ expected="$(printf '%s\n' install.cmd install.ps1 payload.zip payload.zip.sha256 | LC_ALL=C sort)"
+ validate_layout "$extracted" "$expected"
+ (cd "$extracted" && sha256sum -c payload.zip.sha256)
+ cmp "$PWD/install.cmd" "$extracted/install.cmd"
+ cmp "$PWD/install.ps1" "$extracted/install.ps1"
+ cmp "$PAYLOAD_DIR/win32-x64.zip" "$extracted/payload.zip"
- # Summary covers both raw program archives and their offline installer wrappers.
+ # Summary covers the six canonical bundles.
- name: Generate SHA256SUMS
run: |
cd dist-artifacts
diff --git a/README.md b/README.md
index 5dcce859..fc8c7b64 100644
--- a/README.md
+++ b/README.md
@@ -139,31 +139,31 @@ penguin web # start the service and open http://127.0.0.1:7364
```
<details>
-<summary><b>📴 Offline install packages (air-gapped machines)</b></summary>
+<summary><b>📴 Offline install (air-gapped machines)</b></summary>
-Every <a href="https://github.com/Prism-Shadow/penguin-harness/releases">GitHub Release</a> attaches five self-contained offline bundles — Linux and macOS in x64 / arm64, Windows in x64. Each bundle carries the program archive, its SHA256 checksum and the platform's installer: download on a networked machine, copy to the target, and install with no network at all (offline installs verify the SHA256 unconditionally).
+Every <a href="https://github.com/Prism-Shadow/penguin-harness/releases">GitHub Release</a> attaches exactly one package per target — Linux and macOS in x64 / arm64, Windows in x64, plus a runtime-less universal package — and the same file serves online and offline installation. Each package seals the program payload, its SHA256 checksum and the platform's installer: download the one file on a networked machine, copy it to the target, extract once and run the bundled installer — no network, no separate checksum file to carry (the sealed SHA256 is always verified).
-**Linux (on arm64, use `penguin-linux-arm64-offline.tar.gz`):**
+**Linux (on arm64, use `penguin-linux-arm64.tar.gz`):**
```bash
-mkdir penguin-offline
-tar -xzf penguin-linux-x64-offline.tar.gz -C penguin-offline
-./penguin-offline/install.sh
+mkdir penguin-install
+tar -xzf penguin-linux-x64.tar.gz -C penguin-install
+./penguin-install/install.sh
```
-**macOS (Apple silicon shown; on Intel, use `penguin-darwin-x64-offline.tar.gz`):**
+**macOS (Apple silicon shown; on Intel, use `penguin-darwin-x64.tar.gz`):**
```bash
-mkdir penguin-offline
-tar -xzf penguin-darwin-arm64-offline.tar.gz -C penguin-offline
-./penguin-offline/install.sh
+mkdir penguin-install
+tar -xzf penguin-darwin-arm64.tar.gz -C penguin-install
+./penguin-install/install.sh
```
**Windows (unzip, then double-click `install.cmd` — or run it in PowerShell):**
```powershell
-Expand-Archive penguin-win32-x64-offline.zip -DestinationPath penguin-offline
-cd penguin-offline
+Expand-Archive penguin-win32-x64.zip -DestinationPath penguin-install
+cd penguin-install
.\install.cmd
```
diff --git a/README.zh.md b/README.zh.md
index 5d239d96..9abed355 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -139,31 +139,31 @@ penguin web # 启动服务并打开 http://127.0.0.1:7364
```
<details>
-<summary><b>📴 离线安装包(无网环境)</b></summary>
+<summary><b>📴 离线安装(无网环境)</b></summary>
-每个 <a href="https://github.com/Prism-Shadow/penguin-harness/releases">GitHub Release</a> 附带五个自包含的离线安装包——Linux 与 macOS 各有 x64 / arm64 两种架构,Windows 为 x64。包内自带程序压缩包、SHA256 校验文件与对应平台的安装器,在有网机器下载后拷贝到目标机器即可安装,全程无需联网(离线安装强制校验 SHA256)。
+每个 <a href="https://github.com/Prism-Shadow/penguin-harness/releases">GitHub Release</a> 每个目标只附带一个安装包——Linux 与 macOS 各有 x64 / arm64 两种架构,Windows 为 x64,另有不带运行时的 universal 包——同一个文件同时服务在线与离线安装。包内封入程序负载、其 SHA256 校验文件与对应平台的安装器:在有网机器下载这一个文件,拷贝到目标机器,解压一次并运行包内安装器即可——全程无需联网,也不必另外携带校验文件(包内封入的 SHA256 始终强制校验)。
-**Linux(arm64 机器换用 `penguin-linux-arm64-offline.tar.gz`):**
+**Linux(arm64 机器换用 `penguin-linux-arm64.tar.gz`):**
```bash
-mkdir penguin-offline
-tar -xzf penguin-linux-x64-offline.tar.gz -C penguin-offline
-./penguin-offline/install.sh
+mkdir penguin-install
+tar -xzf penguin-linux-x64.tar.gz -C penguin-install
+./penguin-install/install.sh
```
-**macOS(Apple 芯片用 arm64 包,Intel 芯片换用 `penguin-darwin-x64-offline.tar.gz`):**
+**macOS(Apple 芯片用 arm64 包,Intel 芯片换用 `penguin-darwin-x64.tar.gz`):**
```bash
-mkdir penguin-offline
-tar -xzf penguin-darwin-arm64-offline.tar.gz -C penguin-offline
-./penguin-offline/install.sh
+mkdir penguin-install
+tar -xzf penguin-darwin-arm64.tar.gz -C penguin-install
+./penguin-install/install.sh
```
**Windows(解压后双击 `install.cmd`,或在 PowerShell 中运行):**
```powershell
-Expand-Archive penguin-win32-x64-offline.zip -DestinationPath penguin-offline
-cd penguin-offline
+Expand-Archive penguin-win32-x64.zip -DestinationPath penguin-install
+cd penguin-install
.\install.cmd
```
diff --git a/install.cmd b/install.cmd
index 8e2bede8..2ad15f70 100644
--- a/install.cmd
+++ b/install.cmd
@@ -1,7 +1,7 @@
@echo off
setlocal
-powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File "%~dp0install.ps1" -ArchivePath "%~dp0penguin-win32-x64.zip"
+powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File "%~dp0install.ps1" -ArchivePath "%~dp0payload.zip"
set "INSTALL_EXIT_CODE=%ERRORLEVEL%"
echo.
diff --git a/install.ps1 b/install.ps1
index 7ef16da7..a59e4a2c 100644
--- a/install.ps1
+++ b/install.ps1
@@ -7,6 +7,15 @@
# $env:PENGUIN_INSTALL_DIR = "<dir>" install dir; default $env:USERPROFILE\.penguin
# $env:PENGUIN_ARCHIVE = "<file>" install a local Release zip without network access (same as -ArchivePath)
#
+# Each Release attaches exactly one Windows artifact: penguin-win32-x64.zip, a shallow installer
+# bundle holding install.cmd, this script, the program payload (payload.zip) and the payload's
+# checksum. Online installs download that bundle and verify it against its published .sha256;
+# offline installs transfer the same single file, extract it once (the outer layer is flat, so
+# no deep paths are created) and double-click install.cmd. Both paths verify the payload
+# checksum sealed inside the bundle, then expand the payload straight into the short staging
+# directory. Releases up to v0.1.5 shipped the program tree directly (top-level penguin\);
+# such zips are still accepted, from -Version pins and -ArchivePath files alike.
+#
# There is no -Universal on Windows: where the zip is unsuitable, install Node.js >= 24 and run
# `npm install -g @prismshadow/penguin-cli` instead.
#
@@ -25,6 +34,7 @@ $ProgressPreference = "SilentlyContinue" # Invoke-WebRequest progress rendering
$Repo = "https://github.com/Prism-Shadow/penguin-harness"
$Asset = "penguin-win32-x64.zip"
+$PayloadName = "payload.zip"
function Fail([string]$Message) {
# `throw` rather than `exit`: the penguin.ooo forwarder runs this installer as an in-memory
@@ -33,6 +43,30 @@ function Fail([string]$Message) {
throw "error: $Message"
}
+# Lists a zip's top-level entry names without extracting (PS 5.1-safe; Expand-Archive itself
+# uses the same .NET type). Used to tell an installer bundle (contains payload.zip) from a
+# program archive (payload.zip itself, or a pre-0.1.6 release zip with a top-level penguin\).
+function Get-ZipEntryNames([string]$ZipPath) {
+ Add-Type -AssemblyName System.IO.Compression.FileSystem
+ $Zip = [IO.Compression.ZipFile]::OpenRead($ZipPath)
+ try {
+ return @($Zip.Entries | ForEach-Object { $_.FullName })
+ } finally {
+ $Zip.Dispose()
+ }
+}
+
+# Verifies a file against a sha256sum-format checksum file (`<hex> <filename>`; the first
+# token is the hash). Checksums are never optional: every install path either downloads the
+# published .sha256 or reads the one sealed inside the bundle.
+function Assert-Sha256([string]$FilePath, [string]$ShaPath, [string]$Label) {
+ $Expected = ((Get-Content -LiteralPath $ShaPath -Raw).Trim() -split "\s+")[0]
+ if (-not $Expected) { Fail "checksum file is empty or malformed: $ShaPath" }
+ $Actual = (Get-FileHash -Algorithm SHA256 -LiteralPath $FilePath).Hash
+ if ($Actual -ine $Expected) { Fail "checksum mismatch for $([IO.Path]::GetFileName($FilePath))." }
+ Write-Host "$Label checksum OK."
+}
+
function Restore-PreviousInstall(
[string]$InstallDir,
[string]$OldDir,
@@ -63,11 +97,11 @@ if (-not $InstallDir) {
if (-not $ArchivePath) {
$ArchivePath = if ($env:PENGUIN_ARCHIVE) { $env:PENGUIN_ARCHIVE } else { "" }
}
-# An extracted offline bundle keeps this script, the Windows zip and its checksum together.
-# `$PSScriptRoot` is empty for the documented `irm ... | iex` path, so online installs do not
-# accidentally pick up an unrelated archive from the caller's current directory.
+# An extracted installer bundle keeps install.cmd, this script, payload.zip and its checksum
+# together. `$PSScriptRoot` is empty for the documented `irm ... | iex` path, so online installs
+# do not accidentally pick up an unrelated archive from the caller's current directory.
if (-not $ArchivePath -and $PSScriptRoot) {
- $SiblingArchive = Join-Path $PSScriptRoot $Asset
+ $SiblingArchive = Join-Path $PSScriptRoot $PayloadName
if (Test-Path -LiteralPath $SiblingArchive -PathType Leaf) { $ArchivePath = $SiblingArchive }
}
if ($ArchivePath -and $Version) {
@@ -114,6 +148,7 @@ try {
$ArchiveName = [IO.Path]::GetFileName($ZipPath)
Write-Host "Using local archive $ZipPath ..."
} else {
+ # Online: download the canonical bundle; the published checksum is mandatory.
Write-Host "Downloading $BaseUrl/$Asset ..."
$ZipPath = Join-Path $Tmp $Asset
try {
@@ -122,11 +157,42 @@ try {
Fail "download failed. Check the version tag and your network, then retry. ($($_.Exception.Message))"
}
$ArchiveName = $Asset
+ $ShaPath = Join-Path $Tmp "$Asset.sha256"
+ try {
+ Invoke-WebRequest -Uri "$BaseUrl/$Asset.sha256" -OutFile $ShaPath -UseBasicParsing
+ } catch {
+ Fail "checksum download failed. Check the version tag and your network, then retry. ($($_.Exception.Message))"
+ }
+ Assert-Sha256 $ZipPath $ShaPath "Bundle"
}
- # --- SHA256 verify: mandatory offline; online keeps the existing warn-and-skip fallback. ---
- $HaveSha = $true
- if ($UsingLocalArchive) {
+ # --- Resolve the program payload. An installer bundle (contains payload.zip) is opened flat
+ # and its sealed payload checksum verified; a program archive (payload.zip itself, or a
+ # pre-0.1.6 release zip with a top-level penguin\) is used directly. ---
+ $ArchiveShape = if ((Get-ZipEntryNames $ZipPath) -contains $PayloadName) { "bundle" } else { "program" }
+ if ($ArchiveShape -eq "bundle") {
+ # A local bundle is self-verifying through its sealed payload checksum; when the published
+ # outer .sha256 was transferred alongside it, verify that layer too.
+ if ($UsingLocalArchive -and (Test-Path -LiteralPath "$ZipPath.sha256" -PathType Leaf)) {
+ Assert-Sha256 $ZipPath "$ZipPath.sha256" "Bundle"
+ }
+ $BundleDir = Join-Path $Tmp "bundle"
+ New-Item -ItemType Directory -Path $BundleDir | Out-Null
+ Write-Host "Opening installer bundle ..."
+ # The outer layer is flat (four files), so this extraction never creates deep paths.
+ Expand-Archive -LiteralPath $ZipPath -DestinationPath $BundleDir -Force
+ $ZipPath = Join-Path $BundleDir $PayloadName
+ if (-not (Test-Path -LiteralPath $ZipPath -PathType Leaf)) {
+ Fail "unexpected bundle layout: $PayloadName missing."
+ }
+ if (-not (Test-Path -LiteralPath "$ZipPath.sha256" -PathType Leaf)) {
+ Fail "unexpected bundle layout: $PayloadName.sha256 missing."
+ }
+ Assert-Sha256 $ZipPath "$ZipPath.sha256" "Payload"
+ } elseif ($UsingLocalArchive) {
+ # Program archive from disk: an adjacent checksum is required — its own, or the canonical
+ # asset checksum next to a renamed legacy file. (An online download was already verified
+ # against the published .sha256 above.)
$ShaPath = "$ZipPath.sha256"
if (-not (Test-Path -LiteralPath $ShaPath -PathType Leaf) -and
$ArchiveName -ine $Asset) {
@@ -138,24 +204,7 @@ try {
if (-not (Test-Path -LiteralPath $ShaPath -PathType Leaf)) {
Fail "offline checksum file not found: $ShaPath"
}
- } else {
- $ShaPath = Join-Path $Tmp "$Asset.sha256"
- try {
- Invoke-WebRequest -Uri "$BaseUrl/$Asset.sha256" -OutFile $ShaPath -UseBasicParsing
- } catch {
- $HaveSha = $false
- Write-Host "warning: checksum file not available; skipping verification."
- }
- }
- if ($HaveSha) {
- # The .sha256 file is `<hex> <filename>` (sha256sum format); the first token is the hash.
- $Expected = ((Get-Content -LiteralPath $ShaPath -Raw).Trim() -split "\s+")[0]
- $Actual = (Get-FileHash -Algorithm SHA256 -LiteralPath $ZipPath).Hash
- if ($Expected -and ($Actual -ieq $Expected)) {
- Write-Host "Checksum OK."
- } else {
- Fail "checksum mismatch for $Asset."
- }
+ Assert-Sha256 $ZipPath $ShaPath "Payload"
}
# --- Extract into staging, then swap by same-volume renames. Keep the previous dirs in .old.$PID
@@ -187,7 +236,8 @@ try {
if ([string]$TargetProperty.Value -ine "win32-x64") {
Fail "package target mismatch: expected win32-x64, found $($TargetProperty.Value)."
}
- } elseif ($UsingLocalArchive -and $ArchiveName -ine $Asset) {
+ } elseif ($UsingLocalArchive -and $ArchiveShape -eq "program" -and
+ $ArchiveName -ine $Asset -and $ArchiveName -ine $PayloadName) {
Fail "a renamed local archive must contain package-manifest.json; use the original filename for legacy packages."
}
@@ -211,7 +261,13 @@ try {
}
}
- # --- Launcher shims: shipped in the zip; (re)generate only when missing. ---
+ # --- Launcher shim: shipped in the payload; (re)generated only when missing. There is
+ # deliberately no penguin.ps1 launcher — PowerShell would prefer it over penguin.cmd on
+ # PATH, and client Windows defaults to the Restricted execution policy, so a .ps1
+ # launcher makes the plain `penguin` command fail with "running scripts is disabled".
+ # Batch files are policy-exempt and both PowerShell and cmd.exe resolve penguin.cmd.
+ # (bin\ is swapped wholesale above, so upgrading also removes the penguin.ps1 that
+ # pre-0.1.6 payloads shipped.) ---
$CmdShim = Join-Path $InstallDir "bin\penguin.cmd"
if (-not (Test-Path -LiteralPath $CmdShim)) {
@(
@@ -228,19 +284,6 @@ try {
'exit /b %ERRORLEVEL%'
) | Set-Content -LiteralPath $CmdShim -Encoding ascii
}
- $Ps1Shim = Join-Path $InstallDir "bin\penguin.ps1"
- if (-not (Test-Path -LiteralPath $Ps1Shim)) {
- @(
- '$dir = Split-Path -Parent $PSScriptRoot'
- 'if (-not $env:PENGUIN_WEB_DIST) { $env:PENGUIN_WEB_DIST = Join-Path $dir "web" }'
- '$sh = Join-Path $dir "git\usr\bin\sh.exe"'
- 'if (Test-Path $sh) { $env:PENGUIN_BUNDLED_SHELL = $sh }'
- '$node = Join-Path $dir "node\node.exe"'
- 'if (-not (Test-Path $node)) { $node = "node" }'
- '& $node (Join-Path $dir "lib\dist\index.js") @args'
- 'exit $LASTEXITCODE'
- ) | Set-Content -LiteralPath $Ps1Shim -Encoding ascii
- }
if (-not (Test-Path -LiteralPath $CmdShim)) { Fail "install incomplete: $CmdShim missing." }
# Verify from the final path before deleting the backup. Keep stderr visible so platform
@@ -310,7 +353,24 @@ if ($env:OS -eq "Windows_NT") {
if (-not $OnPath) {
$NewPath = if ($RawPath -and -not $RawPath.EndsWith(";")) { "$RawPath;$BinDir" } else { "$RawPath$BinDir" }
$EnvKey.SetValue("Path", $NewPath, $Kind)
- $PathUpdateMessage = "note: installation succeeded and $BinDir was appended to your user Path. Restart your terminal so 'penguin' is found."
+ # A raw registry write does not broadcast WM_SETTINGCHANGE, so Explorer — and every
+ # terminal window launched from it afterwards — would keep the stale Path until the next
+ # logon. Broadcast it the way [Environment]::SetEnvironmentVariable would; best-effort,
+ # a failure only means new terminals need a fresh logon to see the Path.
+ try {
+ if (-not ("PenguinInstaller.NativeMethods" -as [type])) {
+ Add-Type -Namespace PenguinInstaller -Name NativeMethods -MemberDefinition @'
+[System.Runtime.InteropServices.DllImport("user32.dll", SetLastError = true, CharSet = System.Runtime.InteropServices.CharSet.Unicode)]
+public static extern System.IntPtr SendMessageTimeout(System.IntPtr hWnd, uint Msg, System.UIntPtr wParam, string lParam, uint fuFlags, uint uTimeout, out System.UIntPtr lpdwResult);
+'@
+ }
+ $BroadcastResult = [UIntPtr]::Zero
+ # HWND_BROADCAST (0xffff), WM_SETTINGCHANGE (0x1a), SMTO_ABORTIFHUNG (0x2), 5s timeout.
+ [PenguinInstaller.NativeMethods]::SendMessageTimeout([IntPtr]0xffff, 0x1a, [UIntPtr]::Zero,
+ "Environment", 2, 5000, [ref]$BroadcastResult) | Out-Null
+ } catch {
+ }
+ $PathUpdateMessage = "note: installation succeeded and $BinDir was appended to your user Path. Open a new terminal window so 'penguin' is found (a new tab of an already-running terminal keeps the old Path)."
}
} finally {
$EnvKey.Close()
diff --git a/install.sh b/install.sh
index f4f1d404..e6a45df2 100644
--- a/install.sh
+++ b/install.sh
@@ -9,6 +9,15 @@
# PENGUIN_ARCHIVE=<file> install a local Release archive without network access (same as --archive <file>)
# --universal install the universal package (no bundled Node runtime; needs system Node >= 24)
#
+# Each Release attaches exactly one artifact per target: penguin-<target>.tar.gz, a shallow
+# installer bundle holding this script, the program payload (payload.tar.gz) and the payload's
+# checksum. Online installs download that bundle and verify it against its published .sha256;
+# offline installs transfer the same single file, extract it once and run the bundled
+# ./install.sh, which installs the sibling payload with no network access. Both paths verify
+# the payload checksum sealed inside the bundle before anything is staged. Releases up to
+# v0.1.5 shipped the program tree directly (top-level penguin/); such archives are still
+# accepted, from --version pins and --archive files alike.
+#
# The data dir (~/.penguin/data) sits under the install home but is never touched by reinstall/upgrade (which only replace bin/lib/web/node).
#
# Docs: https://penguin.ooo/docs/installation
@@ -20,6 +29,7 @@ INSTALL_DIR="${PENGUIN_INSTALL_DIR:-$HOME/.penguin}"
BIN_DIR="$HOME/.local/bin"
UNIVERSAL=0
ARCHIVE="${PENGUIN_ARCHIVE:-}"
+PAYLOAD_NAME="payload.tar.gz"
fail() {
echo "error: $1" >&2
@@ -51,7 +61,6 @@ done
# --- Detect platform: Linux/Darwin x64/arm64; other platforms should use the universal package ---
TARGET="universal"
-ASSET="penguin-universal.tar.gz"
if [ "$UNIVERSAL" -eq 0 ]; then
case "$(uname -s)" in
Linux) os="linux" ;;
@@ -64,8 +73,8 @@ if [ "$UNIVERSAL" -eq 0 ]; then
*) fail "unsupported architecture: $(uname -m). Install Node.js >= 24, then re-run with --universal." ;;
esac
TARGET="$os-$arch"
- ASSET="penguin-$TARGET.tar.gz"
fi
+ASSET="penguin-$TARGET.tar.gz"
if [ -n "$ARCHIVE" ] && [ -n "$VERSION" ]; then
fail "--archive/PENGUIN_ARCHIVE cannot be combined with --version/PENGUIN_VERSION"
@@ -90,14 +99,47 @@ SWAP_ACTIVE=0
MOVED_OLD=""
MOVED_NEW=""
+# Moves one directory to a new location even when the directory inode itself cannot be renamed
+# — a mount point, a process's CWD, or a filesystem that pins in-use directories (overlayfs
+# under Docker reports EBUSY when `penguin update` replaces the very lib/ its own process runs
+# from). Strategies, in order: plain rename; per-entry renames into a fresh or existing
+# destination; per-entry copy with the source entry removed (POSIX keeps an unlinked-but-open
+# file valid for the process using it). A pinned, now-empty source directory is left in place
+# and reused by the incoming move.
+relocate_dir() {
+ rl_src="$1"
+ rl_dst="$2"
+ if [ ! -e "$rl_dst" ] && mv "$rl_src" "$rl_dst" 2>/dev/null; then
+ return 0
+ fi
+ [ -d "$rl_src" ] || return 1
+ mkdir -p "$rl_dst" || return 1
+ rl_failed=0
+ for rl_entry in "$rl_src"/* "$rl_src"/.[!.]* "$rl_src"/..?*; do
+ [ -e "$rl_entry" ] || [ -L "$rl_entry" ] || continue
+ if ! mv "$rl_entry" "$rl_dst/" 2>/dev/null; then
+ cp -Rp "$rl_entry" "$rl_dst/" || rl_failed=1
+ rm -rf "$rl_entry" || rl_failed=1
+ fi
+ done
+ [ "$rl_failed" -eq 0 ] || return 1
+ [ -z "$(ls -A "$rl_src" 2>/dev/null)" ] || return 1
+ rmdir "$rl_src" 2>/dev/null || :
+ return 0
+}
+
rollback_install() {
rollback_failed=0
for d in $MOVED_NEW; do
- rm -rf "$INSTALL_DIR/$d" || rollback_failed=1
+ # Clearing may leave a pinned-but-empty directory husk; the restore below reuses it.
+ rm -rf "$INSTALL_DIR/$d" 2>/dev/null || :
+ if [ -e "$INSTALL_DIR/$d" ] && [ -n "$(ls -A "$INSTALL_DIR/$d" 2>/dev/null)" ]; then
+ rollback_failed=1
+ fi
done
for d in $MOVED_OLD; do
if [ -e "$OLD_DIR/$d" ]; then
- mv "$OLD_DIR/$d" "$INSTALL_DIR/$d" || rollback_failed=1
+ relocate_dir "$OLD_DIR/$d" "$INSTALL_DIR/$d" || rollback_failed=1
fi
done
if [ "$rollback_failed" -ne 0 ]; then
@@ -125,67 +167,124 @@ trap 'exit 129' HUP
trap 'exit 130' INT
trap 'exit 143' TERM
-# --- Resolve local/offline archive or download from GitHub. ---
+# Verifies file $1 against the sha256sum-format file $2 ($3 names the layer in messages).
+# Checksums are never optional: every install path either downloads the published .sha256 or
+# reads the one sealed inside the bundle.
+verify_sha256() {
+ vs_expected="$(awk 'NR == 1 { print $1 }' "$2" | tr 'A-F' 'a-f')"
+ [ -n "$vs_expected" ] || fail "checksum file is empty or malformed: $2"
+ if command -v sha256sum >/dev/null 2>&1; then
+ vs_actual="$(sha256sum "$1" | awk '{ print $1 }')"
+ elif command -v shasum >/dev/null 2>&1; then
+ vs_actual="$(shasum -a 256 "$1" | awk '{ print $1 }')"
+ else
+ fail "sha256sum or shasum is required for checksum verification"
+ fi
+ [ "$vs_actual" = "$vs_expected" ] || fail "checksum mismatch for $3."
+ echo "$3 checksum OK."
+}
+
+# --- Resolve the program payload. Three entries converge on PAYLOAD_PATH:
+# (a) bundled offline: this script sits next to payload.tar.gz in an extracted bundle;
+# (b) --archive <file>: a local installer bundle, or a payload/legacy program archive;
+# (c) online: download penguin-<target>.tar.gz and verify it, then open it.
+# A bundle is recognized by containing payload.tar.gz at its top level; anything else is a
+# program archive (payload.tar.gz itself, or a pre-0.1.6 release archive) whose top level
+# is penguin/. ---
LOCAL_ARCHIVE=0
-HAVE_SHA=0
-if [ -n "$ARCHIVE" ]; then
+ARCHIVE_SHAPE=""
+ARCHIVE_PATH=""
+ARCHIVE_NAME=""
+PAYLOAD_PATH=""
+
+# Sibling pickup engages only for a real file actually named install.sh — the name it carries
+# inside a bundle. A forwarder or `curl | sh` run never satisfies that (no file, or a random
+# temp name), so an online installer cannot be steered by archives someone planted next to a
+# temporary script in a shared directory.
+SIBLING_PAYLOAD=""
+if [ -z "$ARCHIVE" ] && [ -f "$0" ] && [ "$(basename "$0")" = "install.sh" ]; then
+ script_dir="$(CDPATH= cd "$(dirname "$0")" && pwd)"
+ if [ -f "$script_dir/$PAYLOAD_NAME" ]; then
+ SIBLING_PAYLOAD="$script_dir/$PAYLOAD_NAME"
+ fi
+fi
+
+if [ -n "$SIBLING_PAYLOAD" ]; then
+ # (a) Extracted bundle: install the sibling payload; no network access at all.
+ [ -z "$VERSION" ] \
+ || fail "--version/PENGUIN_VERSION cannot be combined with the bundled offline installer"
+ echo "Using bundled payload $SIBLING_PAYLOAD ..."
+ [ -f "$SIBLING_PAYLOAD.sha256" ] \
+ || fail "offline checksum file not found: $SIBLING_PAYLOAD.sha256"
+ verify_sha256 "$SIBLING_PAYLOAD" "$SIBLING_PAYLOAD.sha256" "Payload"
+ PAYLOAD_PATH="$SIBLING_PAYLOAD"
+ ARCHIVE_NAME="$PAYLOAD_NAME"
+ LOCAL_ARCHIVE=1
+elif [ -n "$ARCHIVE" ]; then
+ # (b) Explicit local archive; its shape is probed below.
[ -f "$ARCHIVE" ] || fail "local archive not found: $ARCHIVE"
archive_name="${ARCHIVE##*/}"
archive_dir="$(CDPATH= cd "$(dirname "$ARCHIVE")" && pwd)"
ARCHIVE_PATH="$archive_dir/$archive_name"
- SHA_PATH="$ARCHIVE_PATH.sha256"
- if [ ! -f "$SHA_PATH" ] && [ "$archive_name" != "$ASSET" ] && [ -f "$archive_dir/$ASSET.sha256" ]; then
- SHA_PATH="$archive_dir/$ASSET.sha256"
- fi
- [ -f "$SHA_PATH" ] || fail "offline checksum file not found: $SHA_PATH"
ARCHIVE_NAME="$archive_name"
LOCAL_ARCHIVE=1
- HAVE_SHA=1
echo "Using local archive $ARCHIVE_PATH ..."
else
+ # (c) Online: download the canonical bundle; the published checksum is mandatory.
if [ -n "$VERSION" ]; then
BASE_URL="$REPO/releases/download/$VERSION"
else
BASE_URL="$REPO/releases/latest/download"
fi
ARCHIVE_PATH="$TMP/$ASSET"
- SHA_PATH="$TMP/$ASSET.sha256"
ARCHIVE_NAME="$ASSET"
echo "Downloading $BASE_URL/$ASSET ..."
curl -fSL --progress-bar "$BASE_URL/$ASSET" -o "$ARCHIVE_PATH" \
|| fail "download failed. Check the version tag and your network, then retry."
- if curl -fsSL "$BASE_URL/$ASSET.sha256" -o "$SHA_PATH" 2>/dev/null; then
- HAVE_SHA=1
- fi
+ curl -fsSL "$BASE_URL/$ASSET.sha256" -o "$TMP/$ASSET.sha256" \
+ || fail "checksum download failed. Check the version tag and your network, then retry."
+ verify_sha256 "$ARCHIVE_PATH" "$TMP/$ASSET.sha256" "Bundle"
fi
-# --- SHA256 verify: mandatory offline; online keeps the existing warn-and-skip fallback. ---
-if [ "$HAVE_SHA" -eq 1 ]; then
- expected="$(awk 'NR == 1 { print $1 }' "$SHA_PATH" | tr 'A-F' 'a-f')"
- [ -n "$expected" ] || fail "checksum file is empty or malformed: $SHA_PATH"
- if command -v sha256sum >/dev/null 2>&1; then
- actual="$(sha256sum "$ARCHIVE_PATH" | awk '{ print $1 }')"
- elif command -v shasum >/dev/null 2>&1; then
- actual="$(shasum -a 256 "$ARCHIVE_PATH" | awk '{ print $1 }')"
+if [ -z "$PAYLOAD_PATH" ]; then
+ if tar -tzf "$ARCHIVE_PATH" 2>/dev/null | head -50 | grep -qE "^(\./)?$PAYLOAD_NAME\$"; then
+ ARCHIVE_SHAPE="bundle"
+ else
+ ARCHIVE_SHAPE="program"
+ fi
+ if [ "$ARCHIVE_SHAPE" = "bundle" ]; then
+ # A local bundle is self-verifying through its sealed payload checksum; when the published
+ # outer .sha256 was transferred alongside it, verify that layer too.
+ if [ "$LOCAL_ARCHIVE" -eq 1 ] && [ -f "$ARCHIVE_PATH.sha256" ]; then
+ verify_sha256 "$ARCHIVE_PATH" "$ARCHIVE_PATH.sha256" "Bundle"
+ fi
+ BUNDLE_DIR="$TMP/bundle"
+ mkdir -p "$BUNDLE_DIR"
+ tar -xzf "$ARCHIVE_PATH" -C "$BUNDLE_DIR"
+ PAYLOAD_PATH="$BUNDLE_DIR/$PAYLOAD_NAME"
+ [ -f "$PAYLOAD_PATH" ] || fail "unexpected bundle layout: $PAYLOAD_NAME missing."
+ [ -f "$PAYLOAD_PATH.sha256" ] || fail "unexpected bundle layout: $PAYLOAD_NAME.sha256 missing."
+ verify_sha256 "$PAYLOAD_PATH" "$PAYLOAD_PATH.sha256" "Payload"
else
+ # Program archive (payload.tar.gz, or a pre-0.1.6 release archive). A local file needs an
+ # adjacent checksum — its own, or the canonical asset checksum next to a renamed legacy
+ # file; an online download was already verified against the published .sha256 above.
if [ "$LOCAL_ARCHIVE" -eq 1 ]; then
- fail "offline installation requires sha256sum or shasum for checksum verification"
+ SHA_PATH="$ARCHIVE_PATH.sha256"
+ if [ ! -f "$SHA_PATH" ] && [ "$ARCHIVE_NAME" != "$ASSET" ] && [ -f "$archive_dir/$ASSET.sha256" ]; then
+ SHA_PATH="$archive_dir/$ASSET.sha256"
+ fi
+ [ -f "$SHA_PATH" ] || fail "offline checksum file not found: $SHA_PATH"
+ verify_sha256 "$ARCHIVE_PATH" "$SHA_PATH" "Payload"
fi
- actual=""
- echo "warning: sha256sum/shasum not found; skipping checksum verification." >&2
- fi
- if [ -n "$actual" ]; then
- [ "$actual" = "$expected" ] || fail "checksum mismatch for $ASSET."
- echo "Checksum OK."
+ PAYLOAD_PATH="$ARCHIVE_PATH"
fi
-else
- echo "warning: checksum file not available; skipping verification." >&2
fi
# --- Extract and validate in staging before touching the current install. The final same-filesystem
# swap keeps the previous dirs in .old.$$ until the installed command runs successfully; any
# move or launch failure restores them automatically. The data dir is never part of the swap. ---
-tar -xzf "$ARCHIVE_PATH" -C "$TMP"
+tar -xzf "$PAYLOAD_PATH" -C "$TMP"
[ -d "$TMP/penguin" ] || fail "unexpected archive layout: top-level penguin/ missing."
MANIFEST_PATH="$TMP/penguin/package-manifest.json"
if [ -f "$MANIFEST_PATH" ]; then
@@ -193,7 +292,7 @@ if [ -f "$MANIFEST_PATH" ]; then
[ -n "$manifest_target" ] || fail "package manifest is malformed: target missing."
[ "$manifest_target" = "$TARGET" ] \
|| fail "package target mismatch: expected $TARGET, found $manifest_target."
-elif [ "$LOCAL_ARCHIVE" -eq 1 ] && [ "$ARCHIVE_NAME" != "$ASSET" ]; then
+elif [ "$LOCAL_ARCHIVE" -eq 1 ] && [ "$ARCHIVE_SHAPE" = "program" ] && [ "$ARCHIVE_NAME" != "$ASSET" ]; then
fail "a renamed local archive must contain package-manifest.json; use the original filename for legacy packages."
fi
mkdir -p "$INSTALL_DIR"
@@ -222,16 +321,16 @@ mkdir -p "$OLD_DIR"
SWAP_ACTIVE=1
for d in bin lib web node; do
if [ -e "$INSTALL_DIR/$d" ]; then
- if mv "$INSTALL_DIR/$d" "$OLD_DIR/$d"; then
+ if relocate_dir "$INSTALL_DIR/$d" "$OLD_DIR/$d"; then
MOVED_OLD="$MOVED_OLD $d"
else
- fail "could not move the existing $d directory aside; the previous installation will be restored."
+ fail "could not move the existing $d directory aside (stop running penguin processes and retry); the previous installation will be restored."
fi
fi
done
for d in bin lib web node; do
if [ -e "$STAGING/$d" ]; then
- if mv "$STAGING/$d" "$INSTALL_DIR/$d"; then
+ if relocate_dir "$STAGING/$d" "$INSTALL_DIR/$d"; then
MOVED_NEW="$MOVED_NEW $d"
else
fail "could not install the new $d directory; the previous installation will be restored."
diff --git a/packages/docs/content/installation.en.md b/packages/docs/content/installation.en.md
index ece007e8..fd409d4f 100644
--- a/packages/docs/content/installation.en.md
+++ b/packages/docs/content/installation.en.md
@@ -17,7 +17,7 @@ On Linux / macOS:
curl -fsSL https://penguin.ooo/install.sh | sh
```
-The script downloads the matching `penguin-{linux,darwin}-{x64,arm64}.tar.gz`, which bundles an official Node.js runtime. Other POSIX platforms do **not** fall back automatically: the script exits and asks you to install Node.js >= 24 and re-run with `--universal`, which selects the runtime-less `penguin-universal.tar.gz` (Windows is served by its own installer below, not by `--universal`).
+The script downloads the matching `penguin-{linux,darwin}-{x64,arm64}.tar.gz` — the canonical installer bundle, sealing the program payload (with an official Node.js runtime), the payload's SHA256 checksum and this same installer. The download is verified against its published `.sha256`, then the sealed payload checksum is verified again before anything is staged. Other POSIX platforms do **not** fall back automatically: the script exits and asks you to install Node.js >= 24 and re-run with `--universal`, which selects the runtime-less `penguin-universal.tar.gz` bundle (Windows is served by its own installer below, not by `--universal`).
On Windows (PowerShell):
@@ -37,14 +37,14 @@ Verify the install:
penguin -v
```
-### Offline bundles
+### Offline install
-Each Release also publishes self-contained offline bundles for Windows x64, Linux x64/arm64 and macOS x64/arm64. Download the bundle matching the target computer on a connected machine, transfer it, then extract it once.
+The same Release artifacts serve offline installation — there is no separate offline package. Download the file matching the target computer on a connected machine (`penguin-<target>.tar.gz`, or `penguin-win32-x64.zip` for Windows), transfer that one file, then extract it once.
On Windows, double-click `install.cmd`, or run:
```powershell
-.\install.ps1 -ArchivePath .\penguin-win32-x64.zip
+.\install.ps1
```
On Linux / macOS, run:
@@ -53,7 +53,7 @@ On Linux / macOS, run:
./install.sh
```
-The extracted bundle keeps the matching program archive, its `.sha256` file and an offline entry point together. The bundle's `install.sh` passes that archive explicitly to the real installer, requires a successful checksum verification and performs no network requests. You can also use the separately published Release installer with an explicit local path: `install.sh --archive <file>`, `PENGUIN_ARCHIVE=<file>`, `install.ps1 -ArchivePath <file>`, or `$env:PENGUIN_ARCHIVE`.
+The extracted bundle keeps the installer, the program payload (`payload.tar.gz` / `payload.zip`) and the payload's `.sha256` together; the installer finds the sibling payload by itself, always verifies the sealed checksum and performs no network requests — no separate checksum file needs to be transferred. You can also point the installer at a file explicitly: `install.sh --archive <file>`, `PENGUIN_ARCHIVE=<file>`, `install.ps1 -ArchivePath <file>`, or `$env:PENGUIN_ARCHIVE` — accepting a Release bundle, its inner payload, or a pre-0.1.6 legacy program archive alike.
### Install location and options
@@ -62,8 +62,8 @@ The extracted bundle keeps the matching program archive, its `.sha256` file and
| Install dir | `~/.penguin` by default; override with the `PENGUIN_INSTALL_DIR` env var |
| Command entry | A symlink `~/.local/bin/penguin` is created (the script warns if `~/.local/bin` is not on PATH) |
| Version pin | `PENGUIN_VERSION=vX.Y.Z` env var, or the `--version vX.Y.Z` script flag; defaults to the latest Release |
-| Local archive | `PENGUIN_ARCHIVE=<file>` or `--archive <file>`; renamed files are accepted with an adjacent `<file>.sha256` or the platform asset's canonical `.sha256` |
-| Integrity check | Downloads are sha256-verified when the Release ships checksum assets |
+| Local archive | `PENGUIN_ARCHIVE=<file>` or `--archive <file>`; accepts a Release bundle (self-verifying via its sealed payload checksum) or a payload/legacy program archive with an adjacent `<file>.sha256` (renamed legacy files may use the platform asset's canonical `.sha256`) |
+| Integrity check | Always on: online downloads are verified against the published `.sha256`, and bundle payloads against the checksum sealed inside the bundle |
| Upgrade | Re-run the install script; files are swapped atomically |
Script flags go after `sh -s --`, e.g. `curl -fsSL https://penguin.ooo/install.sh | sh -s -- --universal`.
@@ -73,17 +73,17 @@ Script flags go after `sh -s --`, e.g. `curl -fsSL https://penguin.ooo/install.s
| Item | Details |
| --- | --- |
| Install dir | `%USERPROFILE%\.penguin` by default; override with the `PENGUIN_INSTALL_DIR` env var |
-| Command entry | `bin\penguin.cmd` and `bin\penguin.ps1` launchers; the installer adds `%USERPROFILE%\.penguin\bin` to your **user** Path (restart the terminal once) |
+| Command entry | the `bin\penguin.cmd` launcher (deliberately no `.ps1` launcher — batch files are exempt from the PowerShell execution policy, so `penguin` works even under the default Restricted policy); the installer adds `%USERPROFILE%\.penguin\bin` to your **user** Path and broadcasts the change — open a **new terminal window** once (a new tab of an already-running terminal keeps the old Path) |
| Version pin | `$env:PENGUIN_VERSION = "vX.Y.Z"` before running the installer |
-| Local archive | `$env:PENGUIN_ARCHIVE = "<file>"` or `-ArchivePath <file>`; renamed files are accepted with an adjacent `<file>.sha256` or `penguin-win32-x64.zip.sha256` |
-| Integrity check | Downloads are sha256-verified when the Release ships checksum assets |
+| Local archive | `$env:PENGUIN_ARCHIVE = "<file>"` or `-ArchivePath <file>`; accepts the Release bundle (self-verifying via its sealed payload checksum) or a payload/legacy zip with an adjacent `<file>.sha256` (renamed legacy files may use `penguin-win32-x64.zip.sha256`) |
+| Integrity check | Always on: online downloads are verified against the published `.sha256`, and bundle payloads against the checksum sealed inside the bundle |
| Upgrade | Re-run the installer; it swaps `bin`/`lib`/`web`/`node` and never touches `data` |
- **Agent shell**: on Windows, the agent's `exec_command` runs in a POSIX shell, for compatibility with skills written for one. It picks, in order: `bash` on PATH (your own [Git for Windows](https://gitforwindows.org/), preferred because it carries the full MSYS userland); then the **bundled bash** — the Windows zip ships MinGit under `git\`, so a machine with no Git for Windows still gets a POSIX shell, about sixty core utilities and `git.exe`; then PowerShell (`pwsh`, then `powershell`). The PowerShell fallback is only reached by npm installs, which bundle nothing. The `PENGUIN_SHELL` env var overrides the pick; the session's system prompt tells the model which shell is active. The bundled shell's licensing is recorded in [THIRD-PARTY-NOTICES.md](https://github.com/Prism-Shadow/penguin-harness/blob/main/THIRD-PARTY-NOTICES.md).
- **Ctrl-C semantics**: on Windows, sending Ctrl-C to a running command session (`input_command` with `"\u0003"`) terminates the whole command session tree instead of interrupting the foreground command — Windows cannot deliver a console Ctrl-C to a piped child process, so the interrupt degrades to a hard tree kill.
- **In-place update**: `penguin update` is not yet supported on Windows — upgrade by re-running the installer above.
- **Config file permissions**: on POSIX, config/credential files are written with `0600` (owner-only) permissions; Windows has no such mode bits, so files fall under your profile's default NTFS ACLs.
-- If PowerShell refuses to run `penguin` with "running scripts is disabled", your execution policy blocks the `penguin.ps1` shim: either call `penguin.cmd` explicitly, or allow local scripts with `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`.
+- If PowerShell refuses to run `penguin` with "running scripts is disabled", the blocked file is a `penguin.ps1` launcher — from an install older than 0.1.6 (re-run the installer: upgrades replace `bin\` and remove it) or generated by an npm global install (call `penguin.cmd` explicitly, or allow local scripts with `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`). The packaged install itself ships only `penguin.cmd`, which runs under any execution policy.
### Data directory
diff --git a/packages/docs/content/installation.zh.md b/packages/docs/content/installation.zh.md
index 140dccea..618d1b50 100644
--- a/packages/docs/content/installation.zh.md
+++ b/packages/docs/content/installation.zh.md
@@ -17,7 +17,7 @@ description: 通过安装脚本、npm 或源码安装 PenguinHarness。
curl -fsSL https://penguin.ooo/install.sh | sh
```
-脚本按平台下载 `penguin-{linux,darwin}-{x64,arm64}.tar.gz`,其中捆绑了官方 Node.js 运行时。其他 POSIX 平台**不会自动回退**:脚本会退出并提示先安装 Node.js >= 24、再携带 `--universal` 重新执行,改用不含运行时的 `penguin-universal.tar.gz`(Windows 使用下方专属安装器,而不是 `--universal`)。
+脚本按平台下载 `penguin-{linux,darwin}-{x64,arm64}.tar.gz`——即标准安装包:包内封入程序负载(捆绑官方 Node.js 运行时)、负载的 SHA256 校验文件与同一个安装器。下载后先对照 Release 发布的 `.sha256` 校验外层,再校验包内封入的负载 checksum,然后才进入暂存安装。其他 POSIX 平台**不会自动回退**:脚本会退出并提示先安装 Node.js >= 24、再携带 `--universal` 重新执行,改用不含运行时的 `penguin-universal.tar.gz` 安装包(Windows 使用下方专属安装器,而不是 `--universal`)。
在 Windows(PowerShell)上执行:
@@ -37,14 +37,14 @@ $env:PENGUIN_VERSION = "vX.Y.Z"; irm https://penguin.ooo/install.ps1 | iex
penguin -v
```
-### 离线安装包
+### 离线安装
-每个 Release 还会分别提供 Windows x64、Linux x64/arm64 与 macOS x64/arm64 的完整离线包。先在可联网电脑上下载与目标电脑匹配的离线包,传输到目标电脑后解压一次。
+离线安装使用与在线安装相同的 Release 制品——不再有单独的离线包。先在可联网电脑上下载与目标电脑匹配的那一个文件(`penguin-<target>.tar.gz`,Windows 为 `penguin-win32-x64.zip`),传输后解压一次。
Windows 上双击 `install.cmd`,或执行:
```powershell
-.\install.ps1 -ArchivePath .\penguin-win32-x64.zip
+.\install.ps1
```
Linux / macOS 上执行:
@@ -53,7 +53,7 @@ Linux / macOS 上执行:
./install.sh
```
-解压后的目录同时包含对应平台的程序压缩包、`.sha256` 文件和离线安装入口。离线包内的 `install.sh` 会将同包内的程序压缩包显式传给实际安装器,强制完成 checksum 校验,并且不会发起任何网络请求。也可以使用 Release 中单独发布的安装器显式指定本地文件:`install.sh --archive <file>`、`PENGUIN_ARCHIVE=<file>`、`install.ps1 -ArchivePath <file>` 或 `$env:PENGUIN_ARCHIVE`。
+解压后的目录同时包含安装器、程序负载(`payload.tar.gz` / `payload.zip`)与负载的 `.sha256`;安装器会自行找到同目录负载,始终校验包内封入的 checksum,且不发起任何网络请求——无需另外传输校验文件。也可以显式指定本地文件:`install.sh --archive <file>`、`PENGUIN_ARCHIVE=<file>`、`install.ps1 -ArchivePath <file>` 或 `$env:PENGUIN_ARCHIVE`——Release 安装包、其内部负载或 0.1.6 之前的旧版程序压缩包均可。
### 安装位置与选项
@@ -62,8 +62,8 @@ Linux / macOS 上执行:
| 安装目录 | 默认 `~/.penguin`,可用环境变量 `PENGUIN_INSTALL_DIR` 覆盖 |
| 命令入口 | 创建符号链接 `~/.local/bin/penguin`(若 `~/.local/bin` 不在 PATH 上,脚本会给出提示) |
| 版本固定 | 环境变量 `PENGUIN_VERSION=vX.Y.Z`,或脚本参数 `--version vX.Y.Z`;默认安装最新 Release |
-| 本地压缩包 | `PENGUIN_ARCHIVE=<file>` 或 `--archive <file>`;允许重命名,要求旁边存在 `<file>.sha256` 或平台标准名称的 `.sha256` |
-| 完整性校验 | Release 提供 checksum 资产时自动进行 sha256 校验 |
+| 本地压缩包 | `PENGUIN_ARCHIVE=<file>` 或 `--archive <file>`;接受 Release 安装包(凭包内封入的负载 checksum 自校验),或旁边带 `<file>.sha256` 的负载 / 旧版程序压缩包(重命名的旧版文件可用平台标准名称的 `.sha256`) |
+| 完整性校验 | 始终进行:在线下载对照发布的 `.sha256` 校验,安装包负载对照包内封入的 checksum 校验 |
| 升级 | 重新执行安装脚本即可,文件原子替换 |
脚本参数写在 `sh -s --` 之后,例如 `curl -fsSL https://penguin.ooo/install.sh | sh -s -- --universal`。
@@ -73,17 +73,17 @@ Linux / macOS 上执行:
| 项目 | 说明 |
| --- | --- |
| 安装目录 | 默认 `%USERPROFILE%\.penguin`,可用环境变量 `PENGUIN_INSTALL_DIR` 覆盖 |
-| 命令入口 | `bin\penguin.cmd` 与 `bin\penguin.ps1` 启动器;安装器会把 `%USERPROFILE%\.penguin\bin` 加入**用户** Path(重启终端后生效) |
+| 命令入口 | `bin\penguin.cmd` 启动器(特意不带 `.ps1` 启动器——批处理不受 PowerShell 执行策略限制,默认 Restricted 策略下 `penguin` 也能直接运行);安装器会把 `%USERPROFILE%\.penguin\bin` 加入**用户** Path 并广播变更——请**新开一个终端窗口**(已开终端的新标签页仍沿用旧 Path) |
| 版本固定 | 运行安装器前设置 `$env:PENGUIN_VERSION = "vX.Y.Z"` |
-| 本地压缩包 | `$env:PENGUIN_ARCHIVE = "<file>"` 或 `-ArchivePath <file>`;允许重命名,要求旁边存在 `<file>.sha256` 或 `penguin-win32-x64.zip.sha256` |
-| 完整性校验 | Release 提供 checksum 资产时自动进行 sha256 校验 |
+| 本地压缩包 | `$env:PENGUIN_ARCHIVE = "<file>"` 或 `-ArchivePath <file>`;接受 Release 安装包(凭包内封入的负载 checksum 自校验),或旁边带 `<file>.sha256` 的负载 / 旧版 zip(重命名的旧版文件可用 `penguin-win32-x64.zip.sha256`) |
+| 完整性校验 | 始终进行:在线下载对照发布的 `.sha256` 校验,安装包负载对照包内封入的 checksum 校验 |
| 升级 | 重新运行安装器;只替换 `bin`/`lib`/`web`/`node`,绝不触碰 `data` |
- **Agent shell**:Windows 上 `exec_command` 在 POSIX shell 中执行,以兼容面向 POSIX 编写的技能生态。选择顺序为:PATH 上的 `bash`(你自己安装的 [Git for Windows](https://gitforwindows.org/),优先,因为它带完整的 MSYS 工具集);其次是**内置 bash**——Windows zip 在 `git\` 下自带 MinGit,因此未安装 Git for Windows 的机器同样有 POSIX shell、约六十个核心工具和 `git.exe`;最后才是 PowerShell(先 `pwsh` 后 `powershell`)。只有经 npm 安装(不含内置包)才会走到 PowerShell。环境变量 `PENGUIN_SHELL` 可强制指定;会话的系统提示词会告知模型当前 shell。内置 shell 的许可信息见 [THIRD-PARTY-NOTICES.md](https://github.com/Prism-Shadow/penguin-harness/blob/main/THIRD-PARTY-NOTICES.md)。
- **Ctrl-C 语义**:Windows 上向运行中的命令会话发送 Ctrl-C(`input_command` 传 `"\u0003"`)会终止整棵命令会话进程树,而不是中断前台命令——Windows 无法向管道子进程投递控制台 Ctrl-C,中断因此退化为整树强杀。
- **就地更新**:`penguin update` 暂不支持 Windows——升级请重新运行上面的安装器。
- **配置文件权限**:POSIX 上配置/凭据文件以 `0600`(仅属主可读写)写入;Windows 没有对应的权限位,文件遵循你用户目录的默认 NTFS ACL。
-- 如果 PowerShell 提示 "running scripts is disabled" 而无法运行 `penguin`,是执行策略拦住了 `penguin.ps1`:可以显式调用 `penguin.cmd`,或用 `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` 允许本地脚本。
+- 如果 PowerShell 提示 "running scripts is disabled" 而无法运行 `penguin`,被拦下的是某个 `penguin.ps1` 启动器——来自 0.1.6 之前的旧安装(重新运行安装器即可:升级会整体替换 `bin\` 并移除它),或来自 npm 全局安装生成的 shim(可显式调用 `penguin.cmd`,或用 `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` 允许本地脚本)。安装包本身只带 `penguin.cmd`,任何执行策略下都能运行。
### 数据目录
diff --git a/packages/landing/public/install.sh b/packages/landing/public/install.sh
index b2348fc7..94ca7286 100644
--- a/packages/landing/public/install.sh
+++ b/packages/landing/public/install.sh
@@ -12,10 +12,13 @@ set -eu
# Download to a file first, then run it: piping straight into `sh` would execute
# a truncated download line by line, and the real installer removes the old
# bin/lib/web/node before moving the new ones in — a cut connection mid-way
-# would leave no install at all.
-TMP="$(mktemp)"
-trap 'rm -f "$TMP"' EXIT
-curl -fsSL "https://github.com/Prism-Shadow/penguin-harness/releases/latest/download/install.sh" -o "$TMP"
+# would leave no install at all. The file lives in a private mktemp -d (0700)
+# directory: the real installer picks up a payload sitting next to a script
+# named install.sh (the extracted-bundle offline path), and a shared /tmp must
+# never offer that seam to other local users.
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+curl -fsSL "https://github.com/Prism-Shadow/penguin-harness/releases/latest/download/install.sh" -o "$TMP_DIR/install.sh"
rc=0
-sh "$TMP" "$@" || rc=$?
+sh "$TMP_DIR/install.sh" "$@" || rc=$?
exit "$rc"
diff --git a/packages/landing/src/lib/links.ts b/packages/landing/src/lib/links.ts
index 080b30d7..7f9b1b03 100644
--- a/packages/landing/src/lib/links.ts
+++ b/packages/landing/src/lib/links.ts
@@ -25,20 +25,21 @@ export const INSTALL_CMD = "curl -fsSL https://penguin.ooo/install.sh | sh";
export const INSTALL_CMD_WINDOWS = "irm https://penguin.ooo/install.ps1 | iex";
/**
- * Offline-bundle install commands, per OS tab of the install switcher. Each Release
- * attaches five self-contained bundles (see scripts/package-offline-bundles.sh); the
- * commands show the most common architecture — the localized hint strings name the
- * alternative archive. Language-neutral, like the one-liners above.
+ * Offline install commands, per OS tab of the install switcher. Each Release attaches one
+ * installer bundle per target (see scripts/package-release-bundles.sh) and the same file
+ * serves online and offline installation; the commands show the most common architecture —
+ * the localized hint strings name the alternative archive. Language-neutral, like the
+ * one-liners above.
*/
export const OFFLINE_INSTALL_CMDS: Record<"linux" | "macos" | "windows", string> = {
- linux: `mkdir penguin-offline
-tar -xzf penguin-linux-x64-offline.tar.gz -C penguin-offline
-./penguin-offline/install.sh`,
- macos: `mkdir penguin-offline
-tar -xzf penguin-darwin-arm64-offline.tar.gz -C penguin-offline
-./penguin-offline/install.sh`,
- windows: `Expand-Archive penguin-win32-x64-offline.zip -DestinationPath penguin-offline
-cd penguin-offline
+ linux: `mkdir penguin-install
+tar -xzf penguin-linux-x64.tar.gz -C penguin-install
+./penguin-install/install.sh`,
+ macos: `mkdir penguin-install
+tar -xzf penguin-darwin-arm64.tar.gz -C penguin-install
+./penguin-install/install.sh`,
+ windows: `Expand-Archive penguin-win32-x64.zip -DestinationPath penguin-install
+cd penguin-install
.\\install.cmd`,
};
diff --git a/packages/landing/src/lib/strings-en.ts b/packages/landing/src/lib/strings-en.ts
index 687eb3bf..fefdf842 100644
--- a/packages/landing/src/lib/strings-en.ts
+++ b/packages/landing/src/lib/strings-en.ts
@@ -71,11 +71,10 @@ export const en: Strings = {
online: "Online install",
offline: "Offline package",
offlineNote:
- "Every GitHub Release attaches five self-contained offline bundles (Linux / macOS in x64 and arm64, Windows in x64), each carrying the program archive, its SHA256 checksum and the installer: download on a networked machine, copy to the target, and install with no network at all.",
+ "Every GitHub Release attaches one package per target (Linux / macOS in x64 and arm64, Windows in x64) and the same file serves online and offline installation. Each package seals the program payload, its SHA256 checksum and the installer: download that one file on a networked machine, copy it to the target, extract once and install with no network at all.",
offlineHints: {
- linux: "On arm64 machines, use penguin-linux-arm64-offline.tar.gz.",
- macos:
- "Apple silicon uses the arm64 bundle; on Intel, use penguin-darwin-x64-offline.tar.gz.",
+ linux: "On arm64 machines, use penguin-linux-arm64.tar.gz.",
+ macos: "Apple silicon uses the arm64 package; on Intel, use penguin-darwin-x64.tar.gz.",
windows: "After unzipping you can also just double-click install.cmd.",
},
offlineRelease: "Download offline packages from GitHub Releases",
diff --git a/packages/landing/src/lib/strings.ts b/packages/landing/src/lib/strings.ts
index f817414c..55acb712 100644
--- a/packages/landing/src/lib/strings.ts
+++ b/packages/landing/src/lib/strings.ts
@@ -77,10 +77,10 @@ export const zh = {
online: "在线安装",
offline: "离线安装包",
offlineNote:
- "每个 GitHub Release 附带五个自包含离线安装包(Linux / macOS 各 x64 与 arm64,Windows 为 x64),内含程序包、SHA256 校验文件与安装器:在有网机器下载,拷贝到目标机器安装,全程无需联网。",
+ "每个 GitHub Release 每个目标只附带一个安装包(Linux / macOS 各 x64 与 arm64,Windows 为 x64),同一个文件同时服务在线与离线安装。包内封入程序负载、SHA256 校验文件与安装器:在有网机器下载这一个文件,拷贝到目标机器解压安装,全程无需联网。",
offlineHints: {
- linux: "arm64 机器换用 penguin-linux-arm64-offline.tar.gz。",
- macos: "Apple 芯片用 arm64 包,Intel 芯片换用 penguin-darwin-x64-offline.tar.gz。",
+ linux: "arm64 机器换用 penguin-linux-arm64.tar.gz。",
+ macos: "Apple 芯片用 arm64 包,Intel 芯片换用 penguin-darwin-x64.tar.gz。",
windows: "解压后也可直接双击 install.cmd 完成安装。",
},
offlineRelease: "前往 GitHub Releases 下载离线安装包",
diff --git a/packages/web/src/components/layout/sidebar.tsx b/packages/web/src/components/layout/sidebar.tsx
index 4079b03c..9963693d 100644
--- a/packages/web/src/components/layout/sidebar.tsx
+++ b/packages/web/src/components/layout/sidebar.tsx
@@ -63,7 +63,7 @@ import { clearDraft, sessionDraftKey } from "../../features/chat/draft-cache";
import { CreateProjectDialog, ProjectSettingsDialog } from "./project-dialogs";
import { ChangePasswordDialog } from "../account/change-password-dialog";
import { UpdateDialog } from "../account/update-dialog";
-import { forceUpdateCheck, useVersionInfo } from "../../lib/use-version-info";
+import { forceUpdateCheck, updateCheckOutcome, useVersionInfo } from "../../lib/use-version-info";
function Icon({ d, size = 16 }: { d: string; size?: number }) {
return (
@@ -244,20 +244,20 @@ export function Sidebar({
/**
* Manual update check (owner request): forces a lookup past the server's TTL cache and
* pushes the result into the shared version-info store, so the reminder rows, badge,
- * and dot appear immediately when a newer release is found — that visible change is
- * the notification then. A toast fires only when nothing changes visibly (#54, one
- * notification per action): up to date, checks disabled, or a failed lookup (the
- * check is fail-soft — failure arrives as the `error` field, not an exception; the
- * catch handles our own server being unreachable).
+ * and dot appear immediately when a newer release is found. Every outcome also toasts —
+ * up to date, found (naming the release; the row below turns into the update entry),
+ * checks disabled, and a failed lookup (the check is fail-soft — failure arrives as the
+ * `error` field, not an exception; the catch handles our own server being unreachable).
*/
const runUpdateCheck = async () => {
if (updateChecking) return;
setUpdateChecking(true);
try {
- const res = await forceUpdateCheck();
- if (res.disabled === true) toastInfo(S.update.checkDisabled);
- else if (res.error !== undefined) toastError(S.update.checkFailed);
- else if (!res.updateAvailable) toastSuccess(S.update.upToDate);
+ const outcome = updateCheckOutcome(await forceUpdateCheck());
+ if (outcome.kind === "disabled") toastInfo(S.update.checkDisabled);
+ else if (outcome.kind === "failed") toastError(S.update.checkFailed);
+ else if (outcome.kind === "found") toastSuccess(S.update.foundNew(outcome.latestVersion));
+ else toastSuccess(S.update.upToDate);
} catch (e) {
toastError(apiErrorText(e));
} finally {
@@ -1099,7 +1099,13 @@ export function Sidebar({
className={`${menuItemClass} flex items-center justify-between gap-2 disabled:cursor-default disabled:opacity-60`}
>
<span className="flex min-w-0 items-center gap-2">
- {newVersion !== null && (
+ {updateChecking && (
+ <span
+ aria-hidden
+ className="inline-block h-3 w-3 shrink-0 animate-spin rounded-full border-[1.5px] border-current border-t-transparent opacity-70"
+ />
+ )}
+ {!updateChecking && newVersion !== null && (
<span
aria-hidden
className="h-2 w-2 shrink-0 rounded-full bg-[var(--accent-bg)]"
diff --git a/packages/web/src/lib/strings-en.ts b/packages/web/src/lib/strings-en.ts
index 0a990193..337ebbce 100644
--- a/packages/web/src/lib/strings-en.ts
+++ b/packages/web/src/lib/strings-en.ts
@@ -67,6 +67,8 @@ export const en: Strings = {
*/
checkNow: "Check for updates",
checking: "Checking…",
+ /** Success toast when the manual check finds a newer release; the row below turns into the update entry. */
+ foundNew: (v: string) => `New version v${v} found — use the update entry below to install`,
upToDate: "You're on the latest version",
checkFailed: "Update check failed — try again later",
checkDisabled: "Update checks are disabled (PENGUIN_UPDATE_CHECK=off)",
diff --git a/packages/web/src/lib/strings.ts b/packages/web/src/lib/strings.ts
index 54318a99..931c7ec9 100644
--- a/packages/web/src/lib/strings.ts
+++ b/packages/web/src/lib/strings.ts
@@ -67,6 +67,8 @@ export const zh = {
*/
checkNow: "检查更新",
checking: "检查中…",
+ /** 手动检查发现新版本时的成功提示;下方同一行即变为更新入口。 */
+ foundNew: (v: string) => `发现新版本 v${v},点击下方更新入口即可安装`,
upToDate: "已是最新版本",
checkFailed: "检查更新失败,请稍后重试",
checkDisabled: "更新检查已关闭(PENGUIN_UPDATE_CHECK=off)",
diff --git a/packages/web/src/lib/use-version-info.ts b/packages/web/src/lib/use-version-info.ts
index 8b1ca0fa..970d3428 100644
--- a/packages/web/src/lib/use-version-info.ts
+++ b/packages/web/src/lib/use-version-info.ts
@@ -28,6 +28,28 @@ let updatePromise: Promise<UpdateCheckResponse> | null = null;
*/
const listeners = new Set<() => void>();
+/** How one manual update check ended, for user feedback — exactly one notice per outcome. */
+export type UpdateCheckOutcome =
+ | { kind: "disabled" }
+ | { kind: "failed" }
+ | { kind: "up-to-date" }
+ | { kind: "found"; latestVersion: string };
+
+/**
+ * Classifies a manual check result. Order matters: `disabled` means no lookup ran, `error`
+ * means the lookup ran and failed (the response is fail-soft, not an exception), and only a
+ * result that names the newer release counts as `found` — updateAvailable without a version
+ * would leave the row and the toast with nothing to show.
+ */
+export function updateCheckOutcome(res: UpdateCheckResponse): UpdateCheckOutcome {
+ if (res.disabled === true) return { kind: "disabled" };
+ if (res.error !== undefined) return { kind: "failed" };
+ if (res.updateAvailable && res.latestVersion !== null) {
+ return { kind: "found", latestVersion: res.latestVersion };
+ }
+ return { kind: "up-to-date" };
+}
+
export interface VersionInfo {
version: VersionResponse | null;
update: UpdateCheckResponse | null;
diff --git a/packages/web/test/update-check-outcome.test.ts b/packages/web/test/update-check-outcome.test.ts
new file mode 100644
index 00000000..8658e098
--- /dev/null
+++ b/packages/web/test/update-check-outcome.test.ts
@@ -0,0 +1,55 @@
+/**
+ * updateCheckOutcome unit tests: the manual "check for updates" action turns one fail-soft
+ * server response into exactly one user notice — disabled beats error, error beats found,
+ * and "found" requires the release to be named so the toast and row have something to show.
+ */
+import { describe, expect, it } from "vitest";
+import type { UpdateCheckResponse } from "@prismshadow/penguin-server/api";
+import { updateCheckOutcome } from "../src/lib/use-version-info";
+
+function response(overrides: Partial<UpdateCheckResponse>): UpdateCheckResponse {
+ return {
+ currentVersion: "0.1.5",
+ buildDate: null,
+ latestVersion: null,
+ updateAvailable: false,
+ releaseUrl: null,
+ publishedAt: null,
+ checkedAt: "2026-08-02T00:00:00.000Z",
+ ...overrides,
+ };
+}
+
+describe("updateCheckOutcome", () => {
+ it("classifies an up-to-date result", () => {
+ expect(updateCheckOutcome(response({ latestVersion: "0.1.5" }))).toEqual({
+ kind: "up-to-date",
+ });
+ });
+
+ it("classifies a newer release with its version", () => {
+ expect(updateCheckOutcome(response({ latestVersion: "0.2.0", updateAvailable: true }))).toEqual(
+ { kind: "found", latestVersion: "0.2.0" },
+ );
+ });
+
+ it("updateAvailable without a named release falls back to up-to-date, never a blank notice", () => {
+ expect(updateCheckOutcome(response({ updateAvailable: true }))).toEqual({
+ kind: "up-to-date",
+ });
+ });
+
+ it("a failed lookup wins over updateAvailable", () => {
+ expect(
+ updateCheckOutcome(
+ response({ error: "network", updateAvailable: true, latestVersion: "0.2.0" }),
+ ),
+ ).toEqual({ kind: "failed" });
+ });
+
+ it("disabled wins over everything — no lookup ran", () => {
+ expect(
+ updateCheckOutcome(response({ disabled: true, error: "network", updateAvailable: true })),
+ ).toEqual({ kind: "disabled" });
+ });
+});
diff --git a/scripts/package-offline-bundles.sh b/scripts/package-offline-bundles.sh
deleted file mode 100644
index eb974b27..00000000
--- a/scripts/package-offline-bundles.sh
+++ /dev/null
@@ -1,87 +0,0 @@
-#!/bin/sh
-# Wrap each platform-specific Release archive with the matching installer and checksum.
-# Relative artifact paths are resolved from the repository root.
-set -eu
-
-ROOT_DIR="$(CDPATH= cd "$(dirname "$0")/.." && pwd)"
-ARTIFACT_INPUT="${1:-dist-artifacts}"
-
-case "$ARTIFACT_INPUT" in
- /*) ARTIFACT_DIR="$ARTIFACT_INPUT" ;;
- *) ARTIFACT_DIR="$ROOT_DIR/$ARTIFACT_INPUT" ;;
-esac
-
-[ -d "$ARTIFACT_DIR" ] || {
- echo "error: artifact directory not found: $ARTIFACT_DIR" >&2
- exit 1
-}
-
-command -v tar >/dev/null 2>&1 || {
- echo "error: tar is required" >&2
- exit 1
-}
-command -v zip >/dev/null 2>&1 || {
- echo "error: zip is required" >&2
- exit 1
-}
-
-write_sha256() {
- file="$1"
- if command -v sha256sum >/dev/null 2>&1; then
- (cd "$(dirname "$file")" && sha256sum "$(basename "$file")" > "$(basename "$file").sha256")
- elif command -v shasum >/dev/null 2>&1; then
- (cd "$(dirname "$file")" && shasum -a 256 "$(basename "$file")" > "$(basename "$file").sha256")
- else
- echo "error: sha256sum or shasum is required" >&2
- exit 1
- fi
-}
-
-require_payload() {
- payload="$1"
- [ -f "$ARTIFACT_DIR/$payload" ] || {
- echo "error: missing payload: $ARTIFACT_DIR/$payload" >&2
- exit 1
- }
- [ -f "$ARTIFACT_DIR/$payload.sha256" ] || {
- echo "error: missing payload checksum: $ARTIFACT_DIR/$payload.sha256" >&2
- exit 1
- }
-}
-
-WORK_DIR="$(mktemp -d)"
-trap 'rm -rf "$WORK_DIR"' EXIT
-
-for target in linux-x64 linux-arm64 darwin-x64 darwin-arm64; do
- payload="penguin-$target.tar.gz"
- output="$ARTIFACT_DIR/penguin-$target-offline.tar.gz"
- bundle="$WORK_DIR/$target"
- require_payload "$payload"
- mkdir -p "$bundle"
- cp "$ARTIFACT_DIR/$payload" "$ARTIFACT_DIR/$payload.sha256" "$bundle/"
- cp "$ROOT_DIR/install.sh" "$bundle/penguin-installer.sh"
- {
- printf '%s\n' '#!/bin/sh'
- printf '%s\n' '# Offline bundle entry point. The payload path is explicit so the online installer never scans its directory.'
- printf '%s\n' 'set -eu'
- printf '%s\n' 'SCRIPT_DIR="$(CDPATH= cd "$(dirname "$0")" && pwd)"'
- printf 'exec sh "$SCRIPT_DIR/penguin-installer.sh" --archive "$SCRIPT_DIR/%s" "$@"\n' "$payload"
- } > "$bundle/install.sh"
- chmod +x "$bundle/install.sh" "$bundle/penguin-installer.sh"
- rm -f "$output" "$output.sha256"
- tar -czf "$output" -C "$bundle" .
- write_sha256 "$output"
- echo "Created $(basename "$output")"
-done
-
-payload="penguin-win32-x64.zip"
-output="$ARTIFACT_DIR/penguin-win32-x64-offline.zip"
-bundle="$WORK_DIR/win32-x64"
-require_payload "$payload"
-mkdir -p "$bundle"
-cp "$ARTIFACT_DIR/$payload" "$ARTIFACT_DIR/$payload.sha256" \
- "$ROOT_DIR/install.ps1" "$ROOT_DIR/install.cmd" "$bundle/"
-rm -f "$output" "$output.sha256"
-(cd "$bundle" && zip -qr "$output" .)
-write_sha256 "$output"
-echo "Created $(basename "$output")"
diff --git a/scripts/package-release-bundles.sh b/scripts/package-release-bundles.sh
new file mode 100755
index 00000000..70d2f262
--- /dev/null
+++ b/scripts/package-release-bundles.sh
@@ -0,0 +1,95 @@
+#!/bin/sh
+# Wrap each program payload with its checksum and native installer into the canonical Release
+# artifact — the only package shape a Release publishes:
+#
+# penguin-<target>.tar.gz = install.sh + payload.tar.gz + payload.tar.gz.sha256
+# penguin-win32-x64.zip = install.cmd + install.ps1 + payload.zip + payload.zip.sha256
+#
+# The same bundle serves online installs (downloaded, outer-verified and opened by install.sh /
+# install.ps1) and offline installs (transfer one file, extract once, run the bundled
+# installer, which verifies and installs the sibling payload with no network). The outer layer
+# stays flat so extracting it never creates deep paths; only the installer expands the payload,
+# inside its short staging directory.
+#
+# Usage: package-release-bundles.sh <payload-dir> [output-dir]
+# <payload-dir> must contain <target>.tar.gz for linux-x64, linux-arm64, darwin-x64,
+# darwin-arm64 and universal, plus win32-x64.zip; relative paths resolve from the repo root.
+set -eu
+
+ROOT_DIR="$(CDPATH= cd "$(dirname "$0")/.." && pwd)"
+PAYLOAD_INPUT="${1:?usage: package-release-bundles.sh <payload-dir> [output-dir]}"
+OUTPUT_INPUT="${2:-dist-artifacts}"
+
+resolve_dir() {
+ case "$1" in
+ /*) printf '%s\n' "$1" ;;
+ *) printf '%s\n' "$ROOT_DIR/$1" ;;
+ esac
+}
+PAYLOAD_DIR="$(resolve_dir "$PAYLOAD_INPUT")"
+OUTPUT_DIR="$(resolve_dir "$OUTPUT_INPUT")"
+
+[ -d "$PAYLOAD_DIR" ] || {
+ echo "error: payload directory not found: $PAYLOAD_DIR" >&2
+ exit 1
+}
+command -v tar >/dev/null 2>&1 || {
+ echo "error: tar is required" >&2
+ exit 1
+}
+command -v zip >/dev/null 2>&1 || {
+ echo "error: zip is required" >&2
+ exit 1
+}
+
+write_sha256() {
+ file="$1"
+ if command -v sha256sum >/dev/null 2>&1; then
+ (cd "$(dirname "$file")" && sha256sum "$(basename "$file")" > "$(basename "$file").sha256")
+ elif command -v shasum >/dev/null 2>&1; then
+ (cd "$(dirname "$file")" && shasum -a 256 "$(basename "$file")" > "$(basename "$file").sha256")
+ else
+ echo "error: sha256sum or shasum is required" >&2
+ exit 1
+ fi
+}
+
+require_payload() {
+ [ -f "$PAYLOAD_DIR/$1" ] || {
+ echo "error: missing payload: $PAYLOAD_DIR/$1" >&2
+ exit 1
+ }
+}
+
+WORK_DIR="$(mktemp -d)"
+trap 'rm -rf "$WORK_DIR"' EXIT
+mkdir -p "$OUTPUT_DIR"
+
+for target in linux-x64 linux-arm64 darwin-x64 darwin-arm64 universal; do
+ payload="$target.tar.gz"
+ output="$OUTPUT_DIR/penguin-$target.tar.gz"
+ bundle="$WORK_DIR/$target"
+ require_payload "$payload"
+ mkdir -p "$bundle"
+ cp "$PAYLOAD_DIR/$payload" "$bundle/payload.tar.gz"
+ write_sha256 "$bundle/payload.tar.gz"
+ cp "$ROOT_DIR/install.sh" "$bundle/install.sh"
+ chmod +x "$bundle/install.sh"
+ rm -f "$output" "$output.sha256"
+ tar -czf "$output" -C "$bundle" .
+ write_sha256 "$output"
+ echo "Created $(basename "$output")"
+done
+
+payload="win32-x64.zip"
+output="$OUTPUT_DIR/penguin-win32-x64.zip"
+bundle="$WORK_DIR/win32-x64"
+require_payload "$payload"
+mkdir -p "$bundle"
+cp "$PAYLOAD_DIR/$payload" "$bundle/payload.zip"
+write_sha256 "$bundle/payload.zip"
+cp "$ROOT_DIR/install.ps1" "$ROOT_DIR/install.cmd" "$bundle/"
+rm -f "$output" "$output.sha256"
+(cd "$bundle" && zip -qr "$output" .)
+write_sha256 "$output"
+echo "Created $(basename "$output")"
diff --git a/scripts/test-installer.ps1 b/scripts/test-installer.ps1
new file mode 100644
index 00000000..bc90365c
--- /dev/null
+++ b/scripts/test-installer.ps1
@@ -0,0 +1,189 @@
+# Hermetic Windows installer tests with tiny fixtures: offline upgrade rollback, canonical
+# bundle installs (local, sibling and online), both checksum layers, no-fallback failures, and
+# pre-0.1.6 legacy archives from pinned versions.
+[CmdletBinding()]
+param()
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+$RepoRoot = Split-Path -Parent $PSScriptRoot
+$Installer = Join-Path $RepoRoot "install.ps1"
+$WorkDir = Join-Path ([IO.Path]::GetTempPath()) "penguin-installer-tests-$PID"
+$OriginalPath = $env:Path
+$OriginalOs = $env:OS
+$Fixture = @{
+ Requests = [Collections.Generic.List[string]]::new()
+ Mode = "canonical"
+ GoodBundle = $null
+ BadInnerBundle = $null
+ LegacyArchive = $null
+}
+$global:PenguinInstallerFixture = $Fixture
+
+function Assert-True([bool]$Condition, [string]$Message) {
+ if (-not $Condition) { throw "test failure: $Message" }
+}
+
+function New-FixtureArchive([string]$Name, [bool]$Fails = $false) {
+ $SourceDir = Join-Path $WorkDir "$Name-source"
+ $PenguinDir = Join-Path $SourceDir "penguin"
+ New-Item -ItemType Directory -Path (Join-Path $PenguinDir "bin") -Force | Out-Null
+ New-Item -ItemType Directory -Path (Join-Path $PenguinDir "lib") -Force | Out-Null
+ $VersionLines = if ($Fails) {
+ @("echo fixture runtime failure 1>&2", "exit /b 42")
+ } else {
+ @("echo fixture-old", "exit /b 0")
+ }
+ @("@echo off", "if `"%~1`"==`"--version`" (") + $VersionLines + @(")", "exit /b 0") |
+ Set-Content -LiteralPath (Join-Path $PenguinDir "bin\penguin.cmd") -Encoding ascii
+ "fixture" | Set-Content -LiteralPath (Join-Path $PenguinDir "lib\fixture.txt") -Encoding ascii
+ @{ schemaVersion = 1; target = "win32-x64" } | ConvertTo-Json -Compress |
+ Set-Content -LiteralPath (Join-Path $PenguinDir "package-manifest.json") -Encoding ascii
+ $Archive = Join-Path $WorkDir "$Name.zip"
+ Compress-Archive -Path $PenguinDir -DestinationPath $Archive -CompressionLevel Fastest
+ $Hash = (Get-FileHash -LiteralPath $Archive -Algorithm SHA256).Hash
+ "$Hash $([IO.Path]::GetFileName($Archive))" |
+ Set-Content -LiteralPath "$Archive.sha256" -Encoding ascii
+ return $Archive
+}
+
+# Serves release assets for the online cases. The new installer never inspects HTTP status
+# codes, so failure modes are plain throws.
+function global:Invoke-WebRequest {
+ param(
+ [Parameter(Mandatory = $true)][string]$Uri,
+ [Parameter(Mandatory = $true)][string]$OutFile,
+ [switch]$UseBasicParsing
+ )
+ $f = $global:PenguinInstallerFixture
+ $f.Requests.Add($Uri)
+ if ($f.Mode -eq "404") { throw "fixture 404: $Uri" }
+ if ($f.Mode -eq "network") { throw "fixture network failure: $Uri" }
+ switch -Wildcard ($Uri) {
+ "*/penguin-win32-x64.zip.sha256" {
+ switch ($f.Mode) {
+ "outer-sha-mismatch" {
+ ("0" * 64) + " penguin-win32-x64.zip" | Set-Content -LiteralPath $OutFile -Encoding ascii
+ }
+ "inner-sha-mismatch" { Copy-Item -LiteralPath "$($f.BadInnerBundle).sha256" -Destination $OutFile }
+ "legacy" { Copy-Item -LiteralPath "$($f.LegacyArchive).sha256" -Destination $OutFile }
+ default { Copy-Item -LiteralPath "$($f.GoodBundle).sha256" -Destination $OutFile }
+ }
+ }
+ "*/penguin-win32-x64.zip" {
+ switch ($f.Mode) {
+ "inner-sha-mismatch" { Copy-Item -LiteralPath $f.BadInnerBundle -Destination $OutFile }
+ "legacy" { Copy-Item -LiteralPath $f.LegacyArchive -Destination $OutFile }
+ default { Copy-Item -LiteralPath $f.GoodBundle -Destination $OutFile }
+ }
+ }
+ default { throw "unexpected fixture request: $Uri" }
+ }
+}
+
+function Invoke-OnlineCase(
+ [string]$Name,
+ [string]$Mode,
+ [string]$Version,
+ [bool]$ShouldSucceed,
+ [int]$ExpectedRequests
+) {
+ $Fixture.Mode = $Mode
+ $Fixture.Requests.Clear()
+ $InstallDir = Join-Path $WorkDir "$Name-install"
+ $Arguments = @{ InstallDir = $InstallDir }
+ if ($Version) { $Arguments.Version = $Version }
+ $Succeeded = $true
+ try { & $Installer @Arguments *>&1 | Out-Null } catch { $Succeeded = $false }
+ Assert-True ($Succeeded -eq $ShouldSucceed) "$Name returned an unexpected result"
+ Assert-True ($Fixture.Requests.Count -eq $ExpectedRequests) `
+ "$Name made $($Fixture.Requests.Count) requests, expected $ExpectedRequests"
+ [PSCustomObject]@{ InstallDir = $InstallDir; Requests = @($Fixture.Requests) }
+}
+
+try {
+ New-Item -ItemType Directory -Path $WorkDir -Force | Out-Null
+ # Keep the fixture tests away from the runner's user registry Path.
+ $env:OS = "PenguinInstallerFixtureTest"
+
+ # --- Offline program archive: good install, then a failing upgrade must roll back. ---
+ $InstallDir = Join-Path $WorkDir "offline-installed"
+ $GoodArchive = New-FixtureArchive "valid"
+ & $Installer -InstallDir $InstallDir -ArchivePath $GoodArchive *>&1 | Out-Null
+
+ $FailedArchive = New-FixtureArchive "failure" $true
+ $Failed = $false
+ try {
+ & $Installer -InstallDir $InstallDir -ArchivePath $FailedArchive *>&1 | Out-Null
+ } catch {
+ $Failed = $true
+ }
+ Assert-True $Failed "failing Windows upgrade unexpectedly succeeded"
+ $Version = & (Join-Path $InstallDir "bin\penguin.cmd") --version
+ Assert-True ($Version -eq "fixture-old") "previous Windows installation was not restored"
+
+ # --- Canonical bundle fixtures: flat outer layer sealing payload.zip + checksum + installers. ---
+ $BundleDir = Join-Path $WorkDir "bundle"
+ New-Item -ItemType Directory -Path $BundleDir | Out-Null
+ Copy-Item $GoodArchive (Join-Path $BundleDir "payload.zip")
+ $PayloadHash = (Get-FileHash -LiteralPath (Join-Path $BundleDir "payload.zip") -Algorithm SHA256).Hash
+ "$PayloadHash payload.zip" |
+ Set-Content -LiteralPath (Join-Path $BundleDir "payload.zip.sha256") -Encoding ascii
+ Copy-Item (Join-Path $RepoRoot "install.ps1"), (Join-Path $RepoRoot "install.cmd") $BundleDir
+ $Fixture.GoodBundle = Join-Path $WorkDir "penguin-win32-x64.zip"
+ Compress-Archive -Path (Join-Path $BundleDir "*") -DestinationPath $Fixture.GoodBundle -CompressionLevel Fastest
+ $GoodHash = (Get-FileHash $Fixture.GoodBundle -Algorithm SHA256).Hash
+ "$GoodHash penguin-win32-x64.zip" |
+ Set-Content -LiteralPath "$($Fixture.GoodBundle).sha256" -Encoding ascii
+
+ $BadBundleDir = Join-Path $WorkDir "bad-bundle"
+ Copy-Item $BundleDir $BadBundleDir -Recurse
+ (("0" * 64) + " payload.zip") |
+ Set-Content (Join-Path $BadBundleDir "payload.zip.sha256") -Encoding ascii
+ $Fixture.BadInnerBundle = Join-Path $WorkDir "bad-inner.zip"
+ Compress-Archive -Path (Join-Path $BadBundleDir "*") -DestinationPath $Fixture.BadInnerBundle
+ $BadHash = (Get-FileHash $Fixture.BadInnerBundle -Algorithm SHA256).Hash
+ "$BadHash penguin-win32-x64.zip" |
+ Set-Content -LiteralPath "$($Fixture.BadInnerBundle).sha256" -Encoding ascii
+
+ $Fixture.LegacyArchive = $GoodArchive
+
+ # --- Local bundle via -ArchivePath: opened flat, sealed payload checksum verified. ---
+ $BundleInstall = Join-Path $WorkDir "bundle-install"
+ & $Installer -InstallDir $BundleInstall -ArchivePath $Fixture.GoodBundle *>&1 | Out-Null
+ $Version = & (Join-Path $BundleInstall "bin\penguin.cmd") --version
+ Assert-True ($Version -eq "fixture-old") "local bundle install did not produce a working command"
+
+ # --- Extracted bundle: install.ps1 next to payload.zip installs it with no network. ---
+ $SiblingDir = Join-Path $WorkDir "sibling"
+ New-Item -ItemType Directory -Path $SiblingDir | Out-Null
+ Expand-Archive -LiteralPath $Fixture.GoodBundle -DestinationPath $SiblingDir
+ $SiblingInstall = Join-Path $WorkDir "sibling-install"
+ $Fixture.Requests.Clear()
+ & (Join-Path $SiblingDir "install.ps1") -InstallDir $SiblingInstall *>&1 | Out-Null
+ Assert-True ($Fixture.Requests.Count -eq 0) "sibling install unexpectedly touched the network"
+ $Version = & (Join-Path $SiblingInstall "bin\penguin.cmd") --version
+ Assert-True ($Version -eq "fixture-old") "sibling install did not produce a working command"
+
+ # --- Online cases. ---
+ $canonical = Invoke-OnlineCase "canonical" "canonical" "" $true 2
+ Assert-True ($canonical.Requests[0] -like "*/releases/latest/download/penguin-win32-x64.zip") `
+ "canonical did not request the canonical bundle"
+ $Version = & (Join-Path $canonical.InstallDir "bin\penguin.cmd") --version
+ Assert-True ($Version -eq "fixture-old") "canonical bundle was not installed"
+ Invoke-OnlineCase "outer-mismatch" "outer-sha-mismatch" "" $false 2 | Out-Null
+ Invoke-OnlineCase "inner-mismatch" "inner-sha-mismatch" "" $false 2 | Out-Null
+ Invoke-OnlineCase "latest-404" "404" "" $false 1 | Out-Null
+ Invoke-OnlineCase "pinned-network" "network" "v0.1.4" $false 1 | Out-Null
+ $pinned = Invoke-OnlineCase "pinned-legacy" "legacy" "v0.1.4" $true 2
+ Assert-True ($pinned.Requests[0] -like "*/releases/download/v0.1.4/penguin-win32-x64.zip") `
+ "pinned legacy did not request the pinned asset"
+
+ Write-Host "Windows installer bundle, offline, rollback and online tests passed."
+} finally {
+ $env:Path = $OriginalPath
+ $env:OS = $OriginalOs
+ Remove-Item Function:\Invoke-WebRequest -ErrorAction SilentlyContinue
+ Remove-Variable PenguinInstallerFixture -Scope Global -ErrorAction SilentlyContinue
+ if (Test-Path -LiteralPath $WorkDir) { Remove-Item -LiteralPath $WorkDir -Recurse -Force }
+}
diff --git a/scripts/test-installer.sh b/scripts/test-installer.sh
new file mode 100755
index 00000000..3e3e78ca
--- /dev/null
+++ b/scripts/test-installer.sh
@@ -0,0 +1,305 @@
+#!/bin/sh
+# Hermetic installer tests with tiny fixtures: canonical bundle layout, offline install with no
+# network, POSIX upgrade rollback, and the online download flow through a stubbed curl
+# (checksum layers, no-fallback failures, pre-0.1.6 legacy archives from pinned versions).
+set -eu
+
+ROOT_DIR="$(CDPATH= cd "$(dirname "$0")/.." && pwd)"
+WORK_DIR="$(mktemp -d)"
+ARTIFACT_DIR="$WORK_DIR/artifacts"
+PAYLOAD_DIR="$WORK_DIR/payloads"
+STUB_BIN="$WORK_DIR/bin"
+TEST_HOME="$WORK_DIR/home"
+trap 'rm -rf "$WORK_DIR"' EXIT HUP INT TERM
+
+fail_test() {
+ echo "test failure: $1" >&2
+ exit 1
+}
+
+write_sha256() {
+ file="$1"
+ (cd "$(dirname "$file")" && sha256sum "$(basename "$file")" > "$(basename "$file").sha256")
+}
+
+make_posix_payload() {
+ target="$1"
+ output="$2"
+ behavior="${3:-success}"
+ payload="$WORK_DIR/payload-src"
+ rm -rf "$payload"
+ mkdir -p "$payload/penguin/bin" "$payload/penguin/lib" "$payload/penguin/web"
+ if [ "$behavior" = "final-failure" ]; then
+ {
+ printf '%s\n' '#!/bin/sh'
+ printf '%s\n' 'case "$0" in'
+ printf '%s\n' ' */.staging.*/bin/penguin) echo fixture-new; exit 0 ;;'
+ printf '%s\n' ' *) echo "fixture final-path failure" >&2; exit 42 ;;'
+ printf '%s\n' 'esac'
+ } > "$payload/penguin/bin/penguin"
+ else
+ {
+ printf '%s\n' '#!/bin/sh'
+ printf 'echo %s\n' "${4:-fixture-old}"
+ } > "$payload/penguin/bin/penguin"
+ fi
+ chmod +x "$payload/penguin/bin/penguin"
+ printf '%s\n' fixture > "$payload/penguin/lib/fixture.txt"
+ mkdir -p "$payload/penguin/lib/vendor"
+ printf '%s\n' vendored > "$payload/penguin/lib/vendor/data.txt"
+ printf '%s\n' fixture > "$payload/penguin/web/index.html"
+ printf '{"schemaVersion":1,"target":"%s"}\n' "$target" > "$payload/penguin/package-manifest.json"
+ tar -czf "$output" -C "$payload" penguin
+}
+
+command -v sha256sum >/dev/null 2>&1 || fail_test "sha256sum is required"
+command -v unzip >/dev/null 2>&1 || fail_test "unzip is required"
+mkdir -p "$ARTIFACT_DIR" "$PAYLOAD_DIR" "$STUB_BIN" "$TEST_HOME"
+
+case "$(uname -s):$(uname -m)" in
+ Linux:x86_64) HOST_TARGET="linux-x64" ;;
+ Linux:aarch64) HOST_TARGET="linux-arm64" ;;
+ Darwin:x86_64) HOST_TARGET="darwin-x64" ;;
+ Darwin:arm64) HOST_TARGET="darwin-arm64" ;;
+ *) fail_test "unsupported fixture platform" ;;
+esac
+HOST_ASSET="penguin-$HOST_TARGET.tar.gz"
+
+# --- Build fixture payloads and package them exactly like the release workflow. ---
+for target in linux-x64 linux-arm64 darwin-x64 darwin-arm64 universal; do
+ make_posix_payload "$target" "$PAYLOAD_DIR/$target.tar.gz"
+done
+windows_payload="$WORK_DIR/windows/penguin"
+mkdir -p "$windows_payload/bin"
+printf '%s\r\n' '@echo off' 'echo fixture-old' > "$windows_payload/bin/penguin.cmd"
+printf '%s\n' '{"schemaVersion":1,"target":"win32-x64"}' > "$windows_payload/package-manifest.json"
+(cd "$WORK_DIR/windows" && zip -qr "$PAYLOAD_DIR/win32-x64.zip" penguin)
+
+sh "$ROOT_DIR/scripts/package-release-bundles.sh" "$PAYLOAD_DIR" "$ARTIFACT_DIR"
+
+# --- Canonical layout: flat bundles, exact member set, byte-identical installers, both
+# checksum layers valid. ---
+for target in linux-x64 linux-arm64 darwin-x64 darwin-arm64 universal; do
+ bundle="$ARTIFACT_DIR/penguin-$target.tar.gz"
+ [ -f "$bundle" ] || fail_test "missing $(basename "$bundle")"
+ (cd "$ARTIFACT_DIR" && sha256sum -c "$(basename "$bundle").sha256" >/dev/null) \
+ || fail_test "outer checksum failed for $(basename "$bundle")"
+ members="$(tar -tzf "$bundle" | sed 's#^\./##' | sed '/^$/d' | LC_ALL=C sort)"
+ expected="$(printf '%s\n' install.sh payload.tar.gz payload.tar.gz.sha256 | LC_ALL=C sort)"
+ [ "$members" = "$expected" ] || fail_test "$(basename "$bundle") has an unexpected layout"
+ extracted="$WORK_DIR/layout-$target"
+ mkdir -p "$extracted"
+ tar -xzf "$bundle" -C "$extracted"
+ [ -x "$extracted/install.sh" ] || fail_test "$(basename "$bundle") installer is not executable"
+ cmp -s "$ROOT_DIR/install.sh" "$extracted/install.sh" \
+ || fail_test "$(basename "$bundle") installer differs from the repository installer"
+ (cd "$extracted" && sha256sum -c payload.tar.gz.sha256 >/dev/null) \
+ || fail_test "$(basename "$bundle") payload checksum failed"
+ cmp -s "$PAYLOAD_DIR/$target.tar.gz" "$extracted/payload.tar.gz" \
+ || fail_test "$(basename "$bundle") payload differs from its input"
+done
+
+windows_bundle="$ARTIFACT_DIR/penguin-win32-x64.zip"
+[ -f "$windows_bundle" ] || fail_test "missing penguin-win32-x64.zip"
+(cd "$ARTIFACT_DIR" && sha256sum -c penguin-win32-x64.zip.sha256 >/dev/null) \
+ || fail_test "outer checksum failed for penguin-win32-x64.zip"
+members="$(unzip -Z1 "$windows_bundle" | LC_ALL=C sort)"
+expected="$(printf '%s\n' install.cmd install.ps1 payload.zip payload.zip.sha256 | LC_ALL=C sort)"
+[ "$members" = "$expected" ] || fail_test "penguin-win32-x64.zip has an unexpected layout"
+extracted="$WORK_DIR/layout-win32-x64"
+mkdir -p "$extracted"
+(cd "$extracted" && unzip -q "$windows_bundle")
+cmp -s "$ROOT_DIR/install.ps1" "$extracted/install.ps1" \
+ || fail_test "Windows bundle installer differs from the repository installer"
+cmp -s "$ROOT_DIR/install.cmd" "$extracted/install.cmd" \
+ || fail_test "Windows bundle install.cmd differs from the repository entry point"
+(cd "$extracted" && sha256sum -c payload.zip.sha256 >/dev/null) \
+ || fail_test "Windows bundle payload checksum failed"
+cmp -s "$PAYLOAD_DIR/win32-x64.zip" "$extracted/payload.zip" \
+ || fail_test "Windows bundle payload differs from its input"
+
+# --- Offline install: extract the bundle once and run its installer, with a curl that always
+# fails first on PATH — the offline path must never touch the network. ---
+cat > "$STUB_BIN/curl" <<'EOF'
+#!/bin/sh
+echo "unexpected network access: curl $*" >&2
+exit 7
+EOF
+chmod +x "$STUB_BIN/curl"
+
+OFFLINE_DIR="$WORK_DIR/offline"
+OFFLINE_INSTALL="$WORK_DIR/offline-install"
+mkdir -p "$OFFLINE_DIR"
+tar -xzf "$ARTIFACT_DIR/$HOST_ASSET" -C "$OFFLINE_DIR"
+HOME="$TEST_HOME" PENGUIN_INSTALL_DIR="$OFFLINE_INSTALL" PATH="$STUB_BIN:$PATH" \
+ sh "$OFFLINE_DIR/install.sh" >/dev/null \
+ || fail_test "offline install from the extracted bundle failed"
+[ "$("$OFFLINE_INSTALL/bin/penguin" --version)" = "fixture-old" ] \
+ || fail_test "offline install did not produce a working command"
+
+# A corrupted extracted payload must be rejected by the sealed checksum.
+CORRUPT_DIR="$WORK_DIR/offline-corrupt"
+mkdir -p "$CORRUPT_DIR"
+tar -xzf "$ARTIFACT_DIR/$HOST_ASSET" -C "$CORRUPT_DIR"
+printf 'corruption' >> "$CORRUPT_DIR/payload.tar.gz"
+set +e
+HOME="$TEST_HOME" PENGUIN_INSTALL_DIR="$WORK_DIR/offline-corrupt-install" PATH="$STUB_BIN:$PATH" \
+ sh "$CORRUPT_DIR/install.sh" >/dev/null 2>&1
+status=$?
+set -e
+[ "$status" -ne 0 ] || fail_test "corrupted offline payload was not rejected"
+
+# --- Local archives: the canonical bundle and a bare payload both install; a failing upgrade
+# rolls back to the previous installation. ---
+LOCAL_INSTALL="$TEST_HOME/.penguin"
+HOME="$TEST_HOME" PENGUIN_INSTALL_DIR="$LOCAL_INSTALL" \
+ sh "$ROOT_DIR/install.sh" --archive "$ARTIFACT_DIR/$HOST_ASSET" >/dev/null \
+ || fail_test "--archive with the canonical bundle failed"
+
+payload_archive="$WORK_DIR/payload.tar.gz"
+cp "$PAYLOAD_DIR/$HOST_TARGET.tar.gz" "$payload_archive"
+write_sha256 "$payload_archive"
+HOME="$TEST_HOME" PENGUIN_INSTALL_DIR="$LOCAL_INSTALL" \
+ sh "$ROOT_DIR/install.sh" --archive "$payload_archive" >/dev/null \
+ || fail_test "--archive with a bare payload failed"
+
+failure_archive="$WORK_DIR/final-failure.tar.gz"
+make_posix_payload "$HOST_TARGET" "$failure_archive" final-failure
+write_sha256 "$failure_archive"
+set +e
+HOME="$TEST_HOME" PENGUIN_INSTALL_DIR="$LOCAL_INSTALL" \
+ sh "$ROOT_DIR/install.sh" --archive "$failure_archive" >/dev/null 2>&1
+status=$?
+set -e
+[ "$status" -ne 0 ] || fail_test "failing POSIX upgrade unexpectedly succeeded"
+[ "$("$LOCAL_INSTALL/bin/penguin" --version)" = "fixture-old" ] \
+ || fail_test "previous POSIX installation was not restored"
+
+# --- Pinned-directory upgrade: emulate a filesystem that refuses to rename in-use directories
+# (overlayfs reports EBUSY when `penguin update` replaces the very lib/ its own process runs
+# from). mv/rmdir stubs refuse directory renames that touch the installed lib, forcing
+# relocate_dir through its per-entry and copy fallbacks and the husk-reuse path. ---
+PINNED_LIB="$LOCAL_INSTALL/lib"
+export PINNED_LIB
+cat > "$STUB_BIN/mv" <<'EOF'
+#!/bin/sh
+if [ -d "$1" ]; then
+ case "$1" in
+ "$PINNED_LIB" | "$PINNED_LIB"/*)
+ echo "mv: cannot move '$1': Device or resource busy" >&2
+ exit 1
+ ;;
+ esac
+fi
+exec /bin/mv "$@"
+EOF
+cat > "$STUB_BIN/rmdir" <<'EOF'
+#!/bin/sh
+case "$1" in
+ "$PINNED_LIB")
+ echo "rmdir: failed to remove '$1': Device or resource busy" >&2
+ exit 1
+ ;;
+esac
+exec /bin/rmdir "$@"
+EOF
+chmod +x "$STUB_BIN/mv" "$STUB_BIN/rmdir"
+
+pinned_archive="$WORK_DIR/pinned-upgrade.tar.gz"
+make_posix_payload "$HOST_TARGET" "$pinned_archive" success fixture-upgraded
+write_sha256 "$pinned_archive"
+HOME="$TEST_HOME" PENGUIN_INSTALL_DIR="$LOCAL_INSTALL" PATH="$STUB_BIN:$PATH" \
+ sh "$ROOT_DIR/install.sh" --archive "$pinned_archive" >/dev/null \
+ || fail_test "upgrade with a pinned lib directory failed"
+rm -f "$STUB_BIN/mv" "$STUB_BIN/rmdir"
+[ "$("$LOCAL_INSTALL/bin/penguin" --version)" = "fixture-upgraded" ] \
+ || fail_test "pinned-lib upgrade did not install the new version"
+[ -f "$LOCAL_INSTALL/lib/vendor/data.txt" ] \
+ || fail_test "pinned-lib upgrade lost the copied lib subdirectory"
+[ -z "$(ls -A "$LOCAL_INSTALL" | grep -E '^\.(old|staging)\.' || :)" ] \
+ || fail_test "pinned-lib upgrade left staging or backup directories behind"
+
+# --- Online flow through a stubbed curl. The canonical bundle is served for current releases;
+# MODE=legacy serves a pre-0.1.6 program archive, which must still install from a pinned
+# version. Checksum failures and download failures must fail without any fallback. ---
+LEGACY_ARCHIVE="$WORK_DIR/legacy.tar.gz"
+make_posix_payload "$HOST_TARGET" "$LEGACY_ARCHIVE"
+write_sha256 "$LEGACY_ARCHIVE"
+
+BAD_DIR="$WORK_DIR/bad-bundle"
+mkdir -p "$BAD_DIR"
+tar -xzf "$ARTIFACT_DIR/$HOST_ASSET" -C "$BAD_DIR"
+printf '%064d payload.tar.gz\n' 0 > "$BAD_DIR/payload.tar.gz.sha256"
+BAD_BUNDLE="$WORK_DIR/bad-bundle.tar.gz"
+tar -czf "$BAD_BUNDLE" -C "$BAD_DIR" .
+write_sha256 "$BAD_BUNDLE"
+
+cat > "$STUB_BIN/curl" <<'EOF'
+#!/bin/sh
+set -eu
+output=""
+url=""
+while [ $# -gt 0 ]; do
+ case "$1" in
+ -o) output="$2"; shift 2 ;;
+ -*) shift ;;
+ *) url="$1"; shift ;;
+ esac
+done
+printf '%s\n' "$url" >> "$REQUEST_LOG"
+base="${url##*/}"
+case "$MODE:$base" in
+ 404:penguin-*) exit 22 ;;
+ network:penguin-*) exit 7 ;;
+ outer-sha-mismatch:penguin-*.sha256) printf '%064d %s\n' 0 "${base%.sha256}" > "$output" ;;
+ outer-sha-mismatch:penguin-*) cp "$ARTIFACT_DIR/$base" "$output" ;;
+ inner-sha-mismatch:penguin-*.sha256) cp "$BAD_BUNDLE.sha256" "$output" ;;
+ inner-sha-mismatch:penguin-*) cp "$BAD_BUNDLE" "$output" ;;
+ legacy:penguin-*.sha256) cp "$LEGACY_ARCHIVE.sha256" "$output" ;;
+ legacy:penguin-*) cp "$LEGACY_ARCHIVE" "$output" ;;
+ canonical:penguin-*.sha256) cp "$ARTIFACT_DIR/$base" "$output" ;;
+ canonical:penguin-*) cp "$ARTIFACT_DIR/$base" "$output" ;;
+ *) echo "unexpected fixture request: $url" >&2; exit 2 ;;
+esac
+EOF
+chmod +x "$STUB_BIN/curl"
+export ARTIFACT_DIR BAD_BUNDLE LEGACY_ARCHIVE
+
+run_online_case() {
+ name="$1"
+ mode="$2"
+ version="$3"
+ expected="$4"
+ expected_requests="$5"
+ CASE_LOG="$WORK_DIR/$name.log"
+ CASE_INSTALL="$WORK_DIR/$name-install"
+ : > "$CASE_LOG"
+ set +e
+ REQUEST_LOG="$CASE_LOG" MODE="$mode" PATH="$STUB_BIN:$PATH" \
+ HOME="$WORK_DIR/$name-home" PENGUIN_INSTALL_DIR="$CASE_INSTALL" \
+ PENGUIN_VERSION="$version" sh "$ROOT_DIR/install.sh" >/dev/null 2>&1
+ status=$?
+ set -e
+ if [ "$expected" = "success" ]; then
+ [ "$status" -eq 0 ] || fail_test "$name unexpectedly failed"
+ else
+ [ "$status" -ne 0 ] || fail_test "$name unexpectedly succeeded"
+ fi
+ [ "$(wc -l < "$CASE_LOG" | tr -d ' ')" -eq "$expected_requests" ] \
+ || fail_test "$name made an unexpected number of requests"
+}
+
+run_online_case canonical canonical "" success 2
+[ "$("$WORK_DIR/canonical-install/bin/penguin" --version)" = "fixture-old" ] \
+ || fail_test "canonical online install did not produce a working command"
+grep -q "/releases/latest/download/$HOST_ASSET\$" "$WORK_DIR/canonical.log" \
+ || fail_test "canonical did not request the canonical bundle"
+run_online_case outer-mismatch outer-sha-mismatch "" failure 2
+run_online_case inner-mismatch inner-sha-mismatch "" failure 2
+run_online_case latest-404 404 "" failure 1
+run_online_case pinned-network network v0.1.4 failure 1
+run_online_case pinned-legacy legacy v0.1.4 success 2
+grep -q "/releases/download/v0.1.4/$HOST_ASSET\$" "$WORK_DIR/pinned-legacy.log" \
+ || fail_test "pinned legacy did not request the pinned asset"
+
+echo "Installer bundle, offline, rollback and online tests passed."
diff --git a/scripts/test-offline-bundles.sh b/scripts/test-offline-bundles.sh
deleted file mode 100644
index 7d42a5bf..00000000
--- a/scripts/test-offline-bundles.sh
+++ /dev/null
@@ -1,105 +0,0 @@
-#!/bin/sh
-# Smoke-test five offline wrappers and POSIX upgrade rollback with tiny fixtures.
-set -eu
-
-ROOT_DIR="$(CDPATH= cd "$(dirname "$0")/.." && pwd)"
-WORK_DIR="$(mktemp -d)"
-ARTIFACT_DIR="$WORK_DIR/artifacts"
-TEST_HOME="$WORK_DIR/home"
-INSTALL_DIR="$TEST_HOME/.penguin"
-trap 'rm -rf "$WORK_DIR"' EXIT HUP INT TERM
-
-fail_test() {
- echo "test failure: $1" >&2
- exit 1
-}
-
-write_sha256() {
- file="$1"
- (cd "$(dirname "$file")" && sha256sum "$(basename "$file")" > "$(basename "$file").sha256")
-}
-
-make_posix_payload() {
- target="$1"
- output="$2"
- behavior="${3:-success}"
- payload="$WORK_DIR/payload"
- rm -rf "$payload"
- mkdir -p "$payload/penguin/bin" "$payload/penguin/lib" "$payload/penguin/web"
- if [ "$behavior" = "final-failure" ]; then
- {
- printf '%s\n' '#!/bin/sh'
- printf '%s\n' 'case "$0" in'
- printf '%s\n' ' */.staging.*/bin/penguin) echo fixture-new; exit 0 ;;'
- printf '%s\n' ' *) echo "fixture final-path failure" >&2; exit 42 ;;'
- printf '%s\n' 'esac'
- } > "$payload/penguin/bin/penguin"
- else
- {
- printf '%s\n' '#!/bin/sh'
- printf '%s\n' 'echo fixture-old'
- } > "$payload/penguin/bin/penguin"
- fi
- chmod +x "$payload/penguin/bin/penguin"
- printf '%s\n' fixture > "$payload/penguin/lib/fixture.txt"
- printf '%s\n' fixture > "$payload/penguin/web/index.html"
- printf '{"schemaVersion":1,"target":"%s"}\n' "$target" > "$payload/penguin/package-manifest.json"
- tar -czf "$output" -C "$payload" penguin
- write_sha256 "$output"
-}
-
-verify_bundle() {
- bundle="$1"
- shift
- [ -f "$bundle" ] || fail_test "missing $(basename "$bundle")"
- [ -f "$bundle.sha256" ] || fail_test "missing $(basename "$bundle").sha256"
- (cd "$(dirname "$bundle")" && sha256sum -c "$(basename "$bundle").sha256" >/dev/null)
- members="$("$@" | sed 's#^\./##' | sed '/^$/d')"
- count="$(printf '%s\n' "$members" | wc -l | tr -d ' ')"
- [ "$count" -eq 4 ] || fail_test "$(basename "$bundle") should contain exactly four files"
-}
-
-command -v sha256sum >/dev/null 2>&1 || fail_test "sha256sum is required"
-command -v unzip >/dev/null 2>&1 || fail_test "unzip is required"
-mkdir -p "$ARTIFACT_DIR" "$TEST_HOME"
-
-for target in linux-x64 linux-arm64 darwin-x64 darwin-arm64; do
- make_posix_payload "$target" "$ARTIFACT_DIR/penguin-$target.tar.gz"
-done
-
-windows_payload="$WORK_DIR/windows/penguin"
-mkdir -p "$windows_payload/bin"
-printf '%s\r\n' '@echo off' 'echo fixture-old' > "$windows_payload/bin/penguin.cmd"
-printf '%s\n' '{"schemaVersion":1,"target":"win32-x64"}' > "$windows_payload/package-manifest.json"
-(cd "$WORK_DIR/windows" && zip -qr "$ARTIFACT_DIR/penguin-win32-x64.zip" penguin)
-write_sha256 "$ARTIFACT_DIR/penguin-win32-x64.zip"
-
-sh "$ROOT_DIR/scripts/package-offline-bundles.sh" "$ARTIFACT_DIR"
-
-for target in linux-x64 linux-arm64 darwin-x64 darwin-arm64; do
- bundle="$ARTIFACT_DIR/penguin-$target-offline.tar.gz"
- verify_bundle "$bundle" tar -tzf "$bundle"
- tar -tzf "$bundle" | grep -q "penguin-$target.tar.gz.sha256" \
- || fail_test "$(basename "$bundle") is missing its payload checksum"
-done
-
-windows_bundle="$ARTIFACT_DIR/penguin-win32-x64-offline.zip"
-verify_bundle "$windows_bundle" unzip -Z1 "$windows_bundle"
-unzip -Z1 "$windows_bundle" | grep -q "penguin-win32-x64.zip.sha256" \
- || fail_test "Windows bundle is missing its payload checksum"
-
-HOME="$TEST_HOME" PENGUIN_INSTALL_DIR="$INSTALL_DIR" \
- sh "$ROOT_DIR/install.sh" --archive "$ARTIFACT_DIR/penguin-linux-x64.tar.gz" >/dev/null
-
-failure_archive="$WORK_DIR/final-failure.tar.gz"
-make_posix_payload linux-x64 "$failure_archive" final-failure
-set +e
-HOME="$TEST_HOME" PENGUIN_INSTALL_DIR="$INSTALL_DIR" \
- sh "$ROOT_DIR/install.sh" --archive "$failure_archive" >/dev/null 2>&1
-status=$?
-set -e
-[ "$status" -ne 0 ] || fail_test "failing POSIX upgrade unexpectedly succeeded"
-[ "$("$INSTALL_DIR/bin/penguin" --version)" = "fixture-old" ] \
- || fail_test "previous POSIX installation was not restored"
-
-echo "Offline bundle and POSIX rollback smoke tests passed."
diff --git a/scripts/test-offline-install.ps1 b/scripts/test-offline-install.ps1
deleted file mode 100644
index 37a66bad..00000000
--- a/scripts/test-offline-install.ps1
+++ /dev/null
@@ -1,65 +0,0 @@
-# Smoke-test Windows offline upgrade rollback with tiny local archives.
-[CmdletBinding()]
-param()
-
-Set-StrictMode -Version Latest
-$ErrorActionPreference = "Stop"
-$RepoRoot = Split-Path -Parent $PSScriptRoot
-$Installer = Join-Path $RepoRoot "install.ps1"
-$WorkDir = Join-Path ([IO.Path]::GetTempPath()) "penguin-offline-install-tests-$PID"
-$OriginalPath = $env:Path
-$OriginalOs = $env:OS
-
-function Assert-True([bool]$Condition, [string]$Message) {
- if (-not $Condition) { throw "test failure: $Message" }
-}
-
-function New-FixtureArchive([string]$Name, [bool]$Fails = $false) {
- $SourceDir = Join-Path $WorkDir "$Name-source"
- $PenguinDir = Join-Path $SourceDir "penguin"
- New-Item -ItemType Directory -Path (Join-Path $PenguinDir "bin") -Force | Out-Null
- New-Item -ItemType Directory -Path (Join-Path $PenguinDir "lib") -Force | Out-Null
- $VersionLines = if ($Fails) {
- @("echo fixture runtime failure 1>&2", "exit /b 42")
- } else {
- @("echo fixture-old", "exit /b 0")
- }
- @("@echo off", "if `"%~1`"==`"--version`" (") + $VersionLines + @(")", "exit /b 0") |
- Set-Content -LiteralPath (Join-Path $PenguinDir "bin\penguin.cmd") -Encoding ascii
- "fixture" | Set-Content -LiteralPath (Join-Path $PenguinDir "lib\fixture.txt") -Encoding ascii
- @{ schemaVersion = 1; target = "win32-x64" } | ConvertTo-Json -Compress |
- Set-Content -LiteralPath (Join-Path $PenguinDir "package-manifest.json") -Encoding ascii
- $Archive = Join-Path $WorkDir "$Name.zip"
- Compress-Archive -Path $PenguinDir -DestinationPath $Archive -CompressionLevel Fastest
- $Hash = (Get-FileHash -LiteralPath $Archive -Algorithm SHA256).Hash
- "$Hash $([IO.Path]::GetFileName($Archive))" |
- Set-Content -LiteralPath "$Archive.sha256" -Encoding ascii
- return $Archive
-}
-
-try {
- New-Item -ItemType Directory -Path $WorkDir -Force | Out-Null
- # Keep the fixture test away from the runner's user registry Path.
- $env:OS = "PenguinInstallerFixtureTest"
- $InstallDir = Join-Path $WorkDir "installed"
- $GoodArchive = New-FixtureArchive "valid"
- & $Installer -InstallDir $InstallDir -ArchivePath $GoodArchive *>&1 | Out-Null
-
- $FailedArchive = New-FixtureArchive "failure" $true
- $Failed = $false
- try {
- & $Installer -InstallDir $InstallDir -ArchivePath $FailedArchive *>&1 | Out-Null
- } catch {
- $Failed = $true
- }
- Assert-True $Failed "failing Windows upgrade unexpectedly succeeded"
- $Version = & (Join-Path $InstallDir "bin\penguin.cmd") --version
- Assert-True ($Version -eq "fixture-old") "previous Windows installation was not restored"
- Write-Host "Windows offline rollback smoke test passed."
-} finally {
- $env:Path = $OriginalPath
- $env:OS = $OriginalOs
- if (Test-Path -LiteralPath $WorkDir) {
- Remove-Item -LiteralPath $WorkDir -Recurse -Force
- }
-}