@beeos-ai/cli 1.0.13 → 1.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beeos-ai/cli",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "type": "module",
   "description": "BeeOS CLI — run AI agents from your desktop",
   "bin": {
@@ -18,7 +18,7 @@
     "build": "tsup",
     "type-check": "tsc --noEmit",
     "lint": "eslint src/",
-    "test": "vitest run --passWithNoTests",
+    "test": "vitest run",
     "prepublishOnly": "pnpm build"
   },
   "dependencies": {

package/scripts/_existing_install_actions.json

@@ -0,0 +1,40 @@
+{
+  "$comment": [
+    "P1-E of the install-link review (shared anchor file).",
+    "",
+    "Three call sites render the 'BeeOS is already installed — what now?'",
+    "menu with subtly different copy:",
+    "",
+    "  1. web/packages/cli/scripts/install.sh   (bash, pre-Node)",
+    "  2. web/packages/cli/scripts/install.ps1  (PowerShell, pre-Node)",
+    "  3. web/packages/cli/src/commands/init.ts (TS, post-Node)",
+    "",
+    "Pre-Node sites can't import TypeScript constants, so we anchor the",
+    "wording with this manifest plus a vitest grep lint",
+    "(`web/packages/cli/src/__tests__/existing-install-actions.test.ts`).",
+    "If you change a label in any of the three files, update the",
+    "matching `keywords` here so the lint stays representative; if you",
+    "add a new action altogether, add a new entry below + render it",
+    "in all three sites."
+  ],
+  "actions": {
+    "upgrade": {
+      "$comment": "Reinstall the CLI to the latest version, then proceed. install.sh/install.ps1 wording differs slightly from init.ts which says 'Upgrade CLI & agents'; both must hit at least one keyword from `keywords`.",
+      "keywords": ["Reinstall", "Upgrade"]
+    },
+    "rerun": {
+      "$comment": "Reuse the existing install (no npm i -g). install.sh/install.ps1 say 'Re-run beeos init', init.ts shows the 'Re-bind' wording for the same conceptual action.",
+      "keywords": ["Re-run", "Re-bind", "Reusing"]
+    },
+    "skip": {
+      "$comment": "Do nothing. Stable wording across all three sites.",
+      "keywords": ["Skip"]
+    }
+  },
+  "$files_root_comment": "Paths below are relative to the `web/` workspace root (the test resolves them against that anchor).",
+  "files": [
+    "packages/cli/scripts/install.sh",
+    "packages/cli/scripts/install.ps1",
+    "packages/core/src/detect.ts"
+  ]
+}

package/scripts/install.Tests.ps1

@@ -0,0 +1,169 @@
+<#
+.SYNOPSIS
+    Pester smoke test for install.ps1 (P2-2 of the install-link review).
+
+.DESCRIPTION
+    The goal of this suite is NOT end-to-end coverage of the install
+    flow — that requires a real Windows host with elevated privileges
+    plus npm/winget/choco mocked, which we do not yet have in CI. The
+    smoke test instead asserts the script's structural integrity:
+
+      1. install.ps1 parses with no syntax errors (caught by the
+         AST parser before any side effect).
+      2. The required helper functions are defined at top level so
+         that future refactors don't accidentally drop them.
+      3. The dry-run hook (`BEEOS_INSTALL_DRY_RUN=1`) exits before
+         performing any network or filesystem write.
+
+    These three properties together make sure that regressions of the
+    "install.sh / install.ps1 没有自动化测试" type from the
+    install-link review get caught at PR time on the
+    install-script-lint workflow.
+#>
+
+# ── Parse-time checks ────────────────────────────────────────
+
+$scriptPath = Join-Path $PSScriptRoot "install.ps1"
+
+Describe "install.ps1 parse-time integrity" {
+    It "exists at the expected path" {
+        Test-Path $scriptPath | Should -Be $true
+    }
+
+    It "parses without syntax errors (AST round-trip)" {
+        $tokens = $null
+        $errors = $null
+        [System.Management.Automation.Language.Parser]::ParseFile(
+            $scriptPath,
+            [ref]$tokens,
+            [ref]$errors
+        ) | Out-Null
+        $errors.Count | Should -Be 0
+    }
+
+    It "declares the expected helper functions" {
+        $tokens = $null
+        $errors = $null
+        $ast = [System.Management.Automation.Language.Parser]::ParseFile(
+            $scriptPath,
+            [ref]$tokens,
+            [ref]$errors
+        )
+
+        $functions = $ast.FindAll({
+            param($node)
+            $node -is [System.Management.Automation.Language.FunctionDefinitionAst]
+        }, $true) | ForEach-Object { $_.Name }
+
+        $expected = @(
+            "Write-BeeInfo",
+            "Write-BeeOk",
+            "Write-BeeWarn",
+            "Write-BeeError",
+            "Test-Platform",
+            "Test-NodeVersion",
+            "Install-NodeAuto",
+            "Show-InstallHints",
+            "Send-Telemetry",
+            "Read-ExistingInstallAction",
+            "Install-DeviceAgentSuite",
+            "Invoke-BeeosCli",
+            # P2-8: PSCore + RunAs auto-elevation helpers.
+            "Test-IsAdministrator",
+            "Request-Elevation"
+        )
+
+        foreach ($name in $expected) {
+            $functions | Should -Contain $name
+        }
+    }
+}
+
+# ── Static guards ────────────────────────────────────────────
+
+Describe "install.ps1 platform guard (P2-8)" {
+    It "contains the non-Windows early-exit branch" {
+        $content = Get-Content -Raw -Path $scriptPath
+        # Look for the marker comment AND the exit branch so a
+        # superficial rename of the variable still trips the test.
+        $content | Should -Match "This installer is Windows-only"
+        $content | Should -Match "exit 2"
+    }
+
+    It "contains a UAC auto-elevation branch" {
+        $content = Get-Content -Raw -Path $scriptPath
+        $content | Should -Match "Start-Process .* -Verb RunAs"
+    }
+
+    It "honours BEEOS_NO_AUTO_ELEVATE=1 as an opt-out" {
+        $content = Get-Content -Raw -Path $scriptPath
+        $content | Should -Match "BEEOS_NO_AUTO_ELEVATE"
+    }
+}
+
+Describe "install.ps1 stdin / TTY handover (P1-J)" {
+    # When stdin is piped (`irm ... | iex`), the child `beeos init`'s
+    # prompts read from the exhausted pipe and silently take defaults.
+    # Mirrors install.sh's `</dev/tty` reattachment.
+    It "detects [Console]::IsInputRedirected" {
+        $content = Get-Content -Raw -Path $scriptPath
+        $content | Should -Match "\[Console\]::IsInputRedirected"
+    }
+
+    It "uses Start-Process with -NoNewWindow when stdin is redirected" {
+        $content = Get-Content -Raw -Path $scriptPath
+        $content | Should -Match "Start-Process .* -NoNewWindow"
+    }
+}
+
+Describe "install.ps1 stderr log file (P1-I)" {
+    # Mirrors install.sh's BEEOS_INSTALL_LOG: winget / choco stderr
+    # MUST land in a forensic file instead of `2>$null`. The lint
+    # below is structural — assert the variable + the redirect appear.
+    It "declares a `$BeeosInstallLog` variable" {
+        $content = Get-Content -Raw -Path $scriptPath
+        $content | Should -Match "BeeosInstallLog"
+    }
+
+    It "redirects winget stderr to the install log" {
+        $content = Get-Content -Raw -Path $scriptPath
+        # `2>>$BeeosInstallLog` is the canonical append-redirect syntax;
+        # `2>$null` here would be a regression to the silent
+        # behaviour the review called out.
+        $content | Should -Match "winget install [^`r`n]+2>>\$BeeosInstallLog"
+    }
+
+    It "redirects choco stderr to the install log" {
+        $content = Get-Content -Raw -Path $scriptPath
+        $content | Should -Match "choco install [^`r`n]+2>>\$BeeosInstallLog"
+    }
+
+    It "Show-InstallHints surfaces the log path on failure" {
+        $content = Get-Content -Raw -Path $scriptPath
+        $content | Should -Match "Installer log:"
+    }
+}
+
+# ── Dry-run hook ─────────────────────────────────────────────
+
+Describe "install.ps1 dry-run hook" {
+    BeforeEach {
+        $script:savedDryRun = $env:BEEOS_INSTALL_DRY_RUN
+    }
+
+    AfterEach {
+        if ($null -eq $script:savedDryRun) {
+            Remove-Item Env:BEEOS_INSTALL_DRY_RUN -ErrorAction SilentlyContinue
+        } else {
+            $env:BEEOS_INSTALL_DRY_RUN = $script:savedDryRun
+        }
+    }
+
+    It "exits cleanly when BEEOS_INSTALL_DRY_RUN=1 is set" {
+        $env:BEEOS_INSTALL_DRY_RUN = "1"
+        # Dot-source so we exercise the param-block + helper definitions
+        # without invoking the main install body. The dry-run hook
+        # `return`s before any state-changing call.
+        { . $scriptPath } | Should -Not -Throw
+    }
+}

package/scripts/install.ps1

@@ -65,6 +65,41 @@ param(
 $ErrorActionPreference = "Stop"
 $MinNodeVersion = 18
 
+# ── PSCore + non-Windows guard (P2-8 of the install-link review) ─────
+#
+# The script header asks for `#Requires -Version 5.1`, but that only
+# rejects Windows PowerShell 2.0/3.0/4.0 hosts — it does NOT block
+# PowerShell Core (`pwsh`) running on macOS / Linux, where most of
+# the cmdlets used below (`winget`, `choco`, `Start-Process -Verb
+# RunAs`, `[Environment]::UserInteractive`) are either missing or
+# behave very differently. Without an explicit check the user gets a
+# stack of opaque errors midway through the script.
+#
+# The check happens BEFORE any helper is even defined so that the
+# message is the first thing the user sees.
+$script:IsWindowsHost = $true
+if ($PSVersionTable.PSEdition -eq "Core") {
+    # PowerShell 6+ exposes the cross-platform `$IsWindows` automatic
+    # variable. Fall back to environment sniffing if some exotic host
+    # somehow strips it (e.g. an embedded runner without the standard
+    # automatic-variable provider — extremely rare but cheap to guard).
+    $autoIsWindows = Get-Variable -Name "IsWindows" -ErrorAction SilentlyContinue
+    if ($autoIsWindows) {
+        $script:IsWindowsHost = [bool]$autoIsWindows.Value
+    } else {
+        $script:IsWindowsHost = ($env:OS -eq "Windows_NT")
+    }
+}
+if (-not $script:IsWindowsHost) {
+    Write-Host ""
+    Write-Host "  This installer is Windows-only." -ForegroundColor Red
+    Write-Host "  On macOS or Linux, please use install.sh instead:" -ForegroundColor Yellow
+    Write-Host ""
+    Write-Host "    curl -fsSL https://beeos.ai/install.sh | bash"
+    Write-Host ""
+    exit 2
+}
+
 $CliPackage = if ($Version -eq "latest") { "@beeos-ai/cli@latest" } else { "@beeos-ai/cli@$Version" }
 
 # Sibling packages installed alongside the CLI so that `beeos device attach`
@@ -87,6 +122,22 @@ if (-not $env:BEEOS_API_URL -or $env:BEEOS_API_URL.Length -eq 0) {
     $script:BeeosApiUrl = $env:BEEOS_API_URL
 }
 
+# P1-I of the install-link review: dump winget/choco stderr to a
+# timestamped log so a Windows install failure leaves a forensic
+# breadcrumb for support. Mirrors `install.sh`'s `BEEOS_INSTALL_LOG`.
+# Honour `$env:BEEOS_INSTALL_LOG` if the caller supplied one (CI may
+# want a deterministic path); otherwise default to a file under
+# `$env:TEMP` named `beeos-install-<timestamp>.log`. The directory
+# must exist before we redirect into it — `$env:TEMP` is guaranteed
+# on Windows, so no `New-Item` ceremony.
+if ($env:BEEOS_INSTALL_LOG -and $env:BEEOS_INSTALL_LOG.Length -gt 0) {
+    $script:BeeosInstallLog = $env:BEEOS_INSTALL_LOG
+} else {
+    $logDir = if ($env:TEMP) { $env:TEMP } else { (Get-Location).Path }
+    $stamp = Get-Date -Format "yyyyMMdd-HHmmss"
+    $script:BeeosInstallLog = Join-Path $logDir ("beeos-install-{0}.log" -f $stamp)
+}
+
 # ── Helpers ──────────────────────────────────────────────────
 
 function Write-BeeInfo  { param([string]$Msg) Write-Host "[beeos] $Msg" -ForegroundColor Cyan }
@@ -97,8 +148,10 @@ function Write-BeeOk    { param([string]$Msg) Write-Host "[beeos] $Msg" -Foregro
 # ── Script-level telemetry (mirror of install.sh send_telemetry) ──
 #
 # Fire-and-forget POST to `/api/v1/telemetry/install`, capped at 2 s,
-# error-swallowing. Matches `web/packages/cli/src/telemetry.ts` event
-# names so dashboard queries don't have to special-case Windows.
+# error-swallowing. Event names + payload shape mirror
+# `web/packages/cli/src/telemetry.ts` (the Node-side source of truth);
+# add an event in BOTH places or the Windows install will silently
+# fall off the dashboard.
 #
 # Opt-out: `$env:BEEOS_NO_TELEMETRY = "1"`.
 function Send-Telemetry {
@@ -203,15 +256,115 @@ function Test-NodeVersion {
 
 # ── Auto-install Node.js ─────────────────────────────────────
 
+# Detect whether the current PowerShell session is running with
+# administrator privileges. winget / choco both need elevation to
+# install machine-wide packages; without this check the failure
+# manifests as opaque "access denied" errors deep inside the package
+# manager output.
+function Test-IsAdministrator {
+    try {
+        $identity = [System.Security.Principal.WindowsIdentity]::GetCurrent()
+        $principal = New-Object System.Security.Principal.WindowsPrincipal($identity)
+        return $principal.IsInRole(
+            [System.Security.Principal.WindowsBuiltInRole]::Administrator
+        )
+    } catch {
+        return $false
+    }
+}
+
+# Re-exec the script in an elevated PowerShell window when the
+# current process is not an administrator. The user sees a UAC
+# prompt; on consent, a fresh `pwsh.exe` / `powershell.exe` runs the
+# same script with the same parameters, and the caller exits cleanly.
+#
+# Returns:
+#   $true  — elevation requested; caller MUST exit immediately.
+#   $false — already elevated, or elevation declined / unavailable.
+#            Caller continues in the original (non-elevated) session.
+function Request-Elevation {
+    if (Test-IsAdministrator) { return $false }
+    if ($env:BEEOS_NO_AUTO_ELEVATE -eq "1") {
+        Write-BeeWarn "BEEOS_NO_AUTO_ELEVATE=1 — skipping auto-elevation."
+        return $false
+    }
+    if (-not [Environment]::UserInteractive) {
+        # Non-interactive shells (CI, piped `irm | iex` without a
+        # console) cannot show a UAC prompt — re-execing would just
+        # spawn a window the user never sees. Bail to the caller's
+        # manual-fix branch instead.
+        Write-BeeWarn "Non-interactive shell — cannot prompt for elevation."
+        return $false
+    }
+
+    Write-BeeInfo "Requesting administrator privileges (UAC prompt) ..."
+    $self = $PSCommandPath
+    if (-not $self) {
+        # `irm | iex` produces no script path; we can't re-exec a
+        # one-liner, so let the caller print manual instructions.
+        Write-BeeWarn "Auto-elevation unavailable when piping the script (irm | iex)."
+        Write-BeeWarn "Please open PowerShell as Administrator and re-run the installer."
+        return $false
+    }
+
+    $pwsh = (Get-Command pwsh -ErrorAction SilentlyContinue).Source
+    if (-not $pwsh) {
+        $pwsh = (Get-Command powershell -ErrorAction SilentlyContinue).Source
+    }
+    if (-not $pwsh) {
+        Write-BeeWarn "Could not locate pwsh.exe / powershell.exe for elevation."
+        return $false
+    }
+
+    $argList = @(
+        "-NoProfile",
+        "-ExecutionPolicy", "Bypass",
+        "-File", $self
+    )
+    if ($Version -ne "latest") { $argList += @("-Version", $Version) }
+    if ($Device) { $argList += "-Device" }
+    if ($Passthrough) { $argList += $Passthrough }
+
+    try {
+        Start-Process -FilePath $pwsh -ArgumentList $argList -Verb RunAs | Out-Null
+        Write-BeeOk "Elevated installer launched in a new window."
+        return $true
+    } catch {
+        Write-BeeWarn "User declined elevation or UAC failed: $_"
+        return $false
+    }
+}
+
 function Install-NodeAuto {
     Write-BeeInfo "Node.js not found. Attempting automatic installation..."
     Write-Host ""
 
+    # Both winget (machine scope) and Chocolatey require admin rights
+    # to write into Program Files and HKLM. Try to escalate once; if
+    # the user accepts UAC the elevated script does the install and
+    # the original (non-elevated) session exits. If they decline we
+    # still try the package managers — winget's user-scope mode and
+    # choco's portable installs work without admin in some cases.
+    if (-not (Test-IsAdministrator)) {
+        if (Request-Elevation) {
+            # Elevated process took over; exit cleanly so the user
+            # doesn't see two installs racing.
+            exit 0
+        }
+        Write-BeeWarn "Continuing without admin — winget/choco may fail with EACCES."
+    }
+
     $winget = Get-Command winget -ErrorAction SilentlyContinue
     if ($winget) {
         Write-BeeInfo "Installing Node.js LTS via winget..."
         try {
-            winget install OpenJS.NodeJS.LTS --accept-package-agreements --accept-source-agreements --silent 2>$null
+            # P1-I: route stderr to $BeeosInstallLog instead of $null
+            # so a failed winget run leaves a breadcrumb. The append
+            # operator (`2>>`) is intentional — we want every line of
+            # output across multiple `Install-NodeAuto` invocations
+            # within a single script run to land in the same file.
+            "[$(Get-Date -Format 'o')] winget install OpenJS.NodeJS.LTS" | Out-File -FilePath $BeeosInstallLog -Append -Encoding utf8
+            winget install OpenJS.NodeJS.LTS --accept-package-agreements --accept-source-agreements --silent 2>>$BeeosInstallLog
             $env:Path = [System.Environment]::GetEnvironmentVariable("Path", "Machine") + ";" +
                         [System.Environment]::GetEnvironmentVariable("Path", "User")
             if (Test-NodeVersion) {
@@ -220,6 +373,7 @@ function Install-NodeAuto {
             }
         } catch {
             Write-BeeWarn "winget install failed: $_"
+            Write-BeeWarn "  see log for details: $BeeosInstallLog"
         }
     }
 
@@ -227,7 +381,8 @@ function Install-NodeAuto {
     if ($choco) {
         Write-BeeInfo "Installing Node.js LTS via Chocolatey..."
         try {
-            choco install nodejs-lts -y 2>$null
+            "[$(Get-Date -Format 'o')] choco install nodejs-lts" | Out-File -FilePath $BeeosInstallLog -Append -Encoding utf8
+            choco install nodejs-lts -y 2>>$BeeosInstallLog
             $env:Path = [System.Environment]::GetEnvironmentVariable("Path", "Machine") + ";" +
                         [System.Environment]::GetEnvironmentVariable("Path", "User")
             if (Test-NodeVersion) {
@@ -236,6 +391,7 @@ function Install-NodeAuto {
             }
         } catch {
             Write-BeeWarn "Chocolatey install failed: $_"
+            Write-BeeWarn "  see log for details: $BeeosInstallLog"
         }
     }
 
@@ -261,6 +417,13 @@ function Show-InstallHints {
     Write-BeeInfo "Then run this script again:"
     Write-Host "  irm https://beeos.ai/install.ps1 | iex"
     Write-Host ""
+    # P1-I: surface the install log so support requests include the
+    # exact winget / choco stderr that explains the failure.
+    if (Test-Path $BeeosInstallLog) {
+        Write-Host "  Installer log:" -ForegroundColor White
+        Write-Host "    $BeeosInstallLog"
+        Write-Host ""
+    }
 }
 
 # ── Existing install detection ───────────────────────────────
@@ -277,17 +440,32 @@ function Get-BeeosVersion {
 }
 
 function Read-ExistingInstallAction {
+    # Note on naming: "Reinstall + upgrade CLI" deliberately differs
+    # from the `beeos init` menu's "Upgrade CLI & agents" item. The
+    # script-side action also re-bootstraps Node / pnpm and re-applies
+    # this shell's env vars before exec'ing the new binary, which the
+    # in-CLI upgrade does NOT do — choosing a different verb keeps the
+    # two flows distinguishable. See `install.sh` for the matching
+    # docstring.
+    #
+    # P1-E of the install-link review: the labels rendered below are
+    # anchored against `install.sh::prompt_existing_install_action` +
+    # `init.ts::decideAction` via
+    # `web/packages/cli/scripts/_existing_install_actions.json` and
+    # the vitest grep lint at
+    # `web/packages/cli/src/__tests__/existing-install-actions.test.ts`.
+    # Keep at least one keyword from `keywords[action]` per option.
     $ver = Get-BeeosVersion
     if (-not $ver) { $ver = "unknown" }
     Write-BeeWarn "BeeOS CLI is already installed (v$ver)."
     Write-Host ""
-    Write-Host "  [1] Upgrade to the latest version and run beeos init"
-    Write-Host "  [2] Re-run beeos init without upgrading"
+    Write-Host "  [1] Reinstall + upgrade CLI to the latest version, then run beeos init"
+    Write-Host "  [2] Re-run beeos init without reinstalling"
     Write-Host "  [3] Skip (do nothing)"
     Write-Host ""
 
     if (-not [Environment]::UserInteractive) {
-        Write-BeeInfo "Non-interactive shell — defaulting to upgrade."
+        Write-BeeInfo "Non-interactive shell — defaulting to reinstall."
         return "upgrade"
     }
 
@@ -367,6 +545,12 @@ function Invoke-BeeosCli {
     Write-BeeInfo "Installing $CliPackage globally..."
     & npm install -g $CliPackage
     if ($LASTEXITCODE -ne 0) {
+        # P0-A of the install-link review: fail-after-bootstrap signal.
+        # The `install.bootstrap.cli_installed` event is only emitted
+        # AFTER npm + the device-agent suite report success, so npm
+        # failures are recorded as a distinct outcome (not as silent
+        # post-success).
+        Send-Telemetry -Event "install.bootstrap.npm_fail" -ErrorCode "npm_install_cli_failed" -Success $false
         Write-BeeError "npm install -g $CliPackage failed."
         Write-BeeError ""
         Write-BeeError "Common fixes:"
@@ -376,11 +560,63 @@ function Invoke-BeeosCli {
         exit 1
     }
     Install-DeviceAgentSuite
+    Send-Telemetry -Event "install.bootstrap.cli_installed"
+
+    # P1-J of the install-link review: when the user invokes the
+    # installer via `irm https://beeos.ai/install.ps1 | iex` the
+    # script's stdin is the pipe from `Invoke-RestMethod`, not the
+    # console. If we then `& beeos @args`, `beeos init`'s prompts read
+    # from that exhausted pipe and silently take their default values
+    # — exactly what install.sh's `</dev/tty` reattachment was added
+    # to prevent on POSIX. We mirror that behaviour here:
+    # `Start-Process -NoNewWindow -Wait` reuses the parent's window
+    # but gives the child a fresh stdin handle attached to the
+    # console, so prompts work as the user expects.
+    $stdinRedirected = $false
+    try {
+        $stdinRedirected = [Console]::IsInputRedirected
+    } catch {
+        # Older / restricted hosts (e.g. ConstrainedLanguage mode)
+        # lose access to [Console]; fall through to the legacy `&`
+        # path rather than blowing up here.
+        $stdinRedirected = $false
+    }
+
+    if ($stdinRedirected -and [Environment]::UserInteractive) {
+        Write-BeeInfo "Detected piped stdin — re-attaching console for interactive prompts."
+        $beeosCmd = Get-Command beeos -ErrorAction SilentlyContinue
+        if ($beeosCmd) {
+            # `-WorkingDirectory` keeps cwd predictable; without it
+            # `Start-Process` defaults to the user's home directory in
+            # some hosts, which surprises later steps.
+            Start-Process -FilePath $beeosCmd.Source `
+                -ArgumentList $args `
+                -NoNewWindow `
+                -Wait `
+                -WorkingDirectory (Get-Location).Path
+            return
+        }
+        # If `beeos` somehow isn't on PATH yet (race with PATH refresh
+        # under a brand-new install), fall through to `&` which will
+        # fail loudly — better than silently consuming a piped EOF.
+    }
+
     & beeos @args
 }
 
 # ── Main ─────────────────────────────────────────────────────
 
+# Dry-run hook for the Pester smoke test (P2-2 of the install-link
+# review). When `BEEOS_INSTALL_DRY_RUN=1` is set, exit BEFORE running
+# any state-changing operation but AFTER all helper functions and
+# `param`-block validation have completed. This lets CI assert
+# "the script parses + every helper is callable" without spawning a
+# real Node install or hitting the telemetry endpoint.
+if ($env:BEEOS_INSTALL_DRY_RUN -eq "1") {
+    Write-Host "[beeos] BEEOS_INSTALL_DRY_RUN=1 — exiting early (smoke test mode)" -ForegroundColor Yellow
+    return
+}
+
 Write-Host ""
 Write-Host "  BeeOS CLI Installer" -ForegroundColor White
 Write-Host "  https://beeos.ai" -ForegroundColor DarkGray
@@ -414,9 +650,10 @@ if ($beeosCmd) {
             exit 0
         }
         "upgrade" {
-            Write-BeeInfo "Upgrading $CliPackage..."
+            Write-BeeInfo "Reinstalling $CliPackage..."
             & npm install -g $CliPackage
             if ($LASTEXITCODE -ne 0) {
+                Send-Telemetry -Event "install.bootstrap.npm_fail" -ErrorCode "npm_install_cli_failed_upgrade" -Success $false
                 Write-BeeError "npm install -g $CliPackage failed."
                 Write-BeeError ""
                 Write-BeeError "Common fixes:"
@@ -436,7 +673,13 @@ if ($beeosCmd) {
 Write-BeeInfo "Running BeeOS CLI..."
 Write-Host ""
 
-Send-Telemetry -Event "install.bootstrap.success"
+# P0-A of the install-link review: this event marks "Node bootstrap
+# finished, about to dispatch into npm install + the CLI". The
+# follow-up `install.bootstrap.cli_installed` (fired inside
+# Invoke-BeeosCli after npm succeeds) is the real "user has working
+# `beeos` on PATH" signal. The two are split so dashboards can tell
+# bootstrap failures apart from npm/CLI failures.
+Send-Telemetry -Event "install.bootstrap.bootstrap_done"
 
 if ($Device) {
     Invoke-BeeosCli -Subcommand "device" -ExtraArgs (@("attach") + $Passthrough)