Release 0.4.2: visible shortcut launcher and auto first-run setup.

Shortcuts no longer fail silently; missing .env triggers bundled setup.

Co-authored-by: Cursor <cursoragent@cursor.com>

packaging/build_release.ps1

@@ -86,7 +86,8 @@ Copy-Item -Path (Join-Path $PSScriptRoot "_common.ps1") -Destination $packOut -F
 foreach ($name in @(
         "download_postgres.ps1", "setup_first_run.ps1", "start_netx_app.ps1",
         "stop_netx_app.ps1", "update_netx.ps1", "check_update.ps1",
-        "netx_tray.ps1", "install_autostart.ps1", "install_service.ps1",
+        "launch_shortcut.ps1", "netx_tray.ps1", "install_autostart.ps1", "install_service.ps1",
+
         "service_run.ps1", "install_update_task.ps1", "sign_release.ps1",
         "build_release.ps1", "publish_release.ps1", "publish_forgejo_release.ps1", "README.md", "manifest.example.json"
     )) {

packaging/installer/netx.iss

@@ -4,7 +4,7 @@
 
 #define MyAppName "NetX"
 #ifndef MyAppVersion
-  #define MyAppVersion "0.4.1"
+  #define MyAppVersion "0.4.2"
 #endif
 #define MyAppPublisher "NetX"
 #define MyAppURL "https://github.com/hansjone/netx"
@@ -75,16 +75,16 @@ Name: "{commonappdata}\NetX\pgdata"
 Name: "{commonappdata}\NetX\backups"
 
 [Icons]
-Name: "{group}\NetX Tray"; Filename: "powershell.exe"; Parameters: "-NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File ""{app}\packaging\netx_tray.ps1"" -ProgramRoot ""{app}"" -DataRoot ""{commonappdata}\NetX"" -StartOnLaunch"; WorkingDir: "{app}"; IconFilename: "{app}\packaging\assets\netx.ico"
-Name: "{group}\Start NetX"; Filename: "powershell.exe"; Parameters: "-ExecutionPolicy Bypass -File ""{app}\packaging\start_netx_app.ps1"" -ProgramRoot ""{app}"" -DataRoot ""{commonappdata}\NetX"""; WorkingDir: "{app}"; IconFilename: "{app}\packaging\assets\netx.ico"
-Name: "{group}\Stop NetX"; Filename: "powershell.exe"; Parameters: "-ExecutionPolicy Bypass -File ""{app}\packaging\stop_netx_app.ps1"" -ProgramRoot ""{app}"" -DataRoot ""{commonappdata}\NetX"""; WorkingDir: "{app}"; IconFilename: "{app}\packaging\assets\netx.ico"
-Name: "{group}\Check for updates"; Filename: "powershell.exe"; Parameters: "-ExecutionPolicy Bypass -File ""{app}\packaging\check_update.ps1"" -ProgramRoot ""{app}"" -DataRoot ""{commonappdata}\NetX"""; WorkingDir: "{app}"; IconFilename: "{app}\packaging\assets\netx.ico"
+Name: "{group}\NetX Tray"; Filename: "powershell.exe"; Parameters: "-NoProfile -ExecutionPolicy Bypass -File ""{app}\packaging\launch_shortcut.ps1"" -Action tray -ProgramRoot ""{app}"" -DataRoot ""{commonappdata}\NetX"" -StartOnLaunch"; WorkingDir: "{app}"; IconFilename: "{app}\packaging\assets\netx.ico"
+Name: "{group}\Start NetX"; Filename: "powershell.exe"; Parameters: "-NoProfile -ExecutionPolicy Bypass -File ""{app}\packaging\launch_shortcut.ps1"" -Action start -ProgramRoot ""{app}"" -DataRoot ""{commonappdata}\NetX"""; WorkingDir: "{app}"; IconFilename: "{app}\packaging\assets\netx.ico"
+Name: "{group}\Stop NetX"; Filename: "powershell.exe"; Parameters: "-NoProfile -ExecutionPolicy Bypass -File ""{app}\packaging\launch_shortcut.ps1"" -Action stop -ProgramRoot ""{app}"" -DataRoot ""{commonappdata}\NetX"""; WorkingDir: "{app}"; IconFilename: "{app}\packaging\assets\netx.ico"
+Name: "{group}\Check for updates"; Filename: "powershell.exe"; Parameters: "-NoProfile -ExecutionPolicy Bypass -File ""{app}\packaging\launch_shortcut.ps1"" -Action update -ProgramRoot ""{app}"" -DataRoot ""{commonappdata}\NetX"""; WorkingDir: "{app}"; IconFilename: "{app}\packaging\assets\netx.ico"
 Name: "{group}\Open NetX UI"; Filename: "http://127.0.0.1:8890/"; IconFilename: "{app}\packaging\assets\netx.ico"
-Name: "{group}\First-time setup"; Filename: "powershell.exe"; Parameters: "-ExecutionPolicy Bypass -File ""{app}\packaging\setup_first_run.ps1"" -ProgramRoot ""{app}"" -DataRoot ""{commonappdata}\NetX"""; WorkingDir: "{app}"; IconFilename: "{app}\packaging\assets\netx.ico"
+Name: "{group}\First-time setup"; Filename: "powershell.exe"; Parameters: "-NoProfile -ExecutionPolicy Bypass -File ""{app}\packaging\launch_shortcut.ps1"" -Action setup -ProgramRoot ""{app}"" -DataRoot ""{commonappdata}\NetX"""; WorkingDir: "{app}"; IconFilename: "{app}\packaging\assets\netx.ico"
 Name: "{group}\Install Windows Service (admin)"; Filename: "powershell.exe"; Parameters: "-ExecutionPolicy Bypass -File ""{app}\packaging\install_service.ps1"" -ProgramRoot ""{app}"" -DataRoot ""{commonappdata}\NetX"" -Start"; WorkingDir: "{app}"; IconFilename: "{app}\packaging\assets\netx.ico"
 Name: "{group}\Enable silent auto-update (daily)"; Filename: "powershell.exe"; Parameters: "-ExecutionPolicy Bypass -File ""{app}\packaging\install_update_task.ps1"" -ProgramRoot ""{app}"" -DataRoot ""{commonappdata}\NetX"""; WorkingDir: "{app}"; IconFilename: "{app}\packaging\assets\netx.ico"
 Name: "{group}\Enable start at logon"; Filename: "powershell.exe"; Parameters: "-ExecutionPolicy Bypass -File ""{app}\packaging\install_autostart.ps1"" -ProgramRoot ""{app}"""; WorkingDir: "{app}"; IconFilename: "{app}\packaging\assets\netx.ico"
-Name: "{autodesktop}\NetX"; Filename: "powershell.exe"; Parameters: "-NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File ""{app}\packaging\netx_tray.ps1"" -ProgramRoot ""{app}"" -DataRoot ""{commonappdata}\NetX"" -StartOnLaunch"; WorkingDir: "{app}"; IconFilename: "{app}\packaging\assets\netx.ico"; Tasks: desktopicon
+Name: "{autodesktop}\NetX"; Filename: "powershell.exe"; Parameters: "-NoProfile -ExecutionPolicy Bypass -File ""{app}\packaging\launch_shortcut.ps1"" -Action tray -ProgramRoot ""{app}"" -DataRoot ""{commonappdata}\NetX"" -StartOnLaunch"; WorkingDir: "{app}"; IconFilename: "{app}\packaging\assets\netx.ico"; Tasks: desktopicon
 
 [Run]
 ; First-run is NonInteractive + bundled DB so offline machines succeed without prompts or downloads.

packaging/launch_shortcut.ps1

@@ -0,0 +1,107 @@
+param(
+    [ValidateSet("tray", "start", "stop", "setup", "update")]
+    [string]$Action = "tray",
+    [string]$ProgramRoot = "",
+    [string]$DataRoot = "",
+    [switch]$StartOnLaunch = $true
+)
+
+# Visible entrypoint for Start Menu / desktop shortcuts.
+# Shows a message box on failure (explorer-launched PowerShell otherwise flashes and exits).
+
+$ErrorActionPreference = "Stop"
+. "$PSScriptRoot\_common.ps1"
+
+Add-Type -AssemblyName System.Windows.Forms
+
+$zh = ([cultureinfo]::CurrentUICulture.Name -match '^(zh|zh-)')
+function T([string]$En, [string]$Zh) {
+    if ($zh) { return $Zh } else { return $En }
+}
+
+$prog = Get-NetxProgramRoot -Override $ProgramRoot
+$data = Get-NetxDataRoot -ProgramRoot $prog -Override $DataRoot
+$logDir = Join-Path $data "data\runtime"
+if (-not (Test-Path $logDir)) {
+    New-Item -ItemType Directory -Path $logDir -Force | Out-Null
+}
+$log = Join-Path $logDir "launch.log"
+
+function Write-LaunchLog([string]$Msg) {
+    $line = "[{0}] {1}" -f (Get-Date -Format "yyyy-MM-dd HH:mm:ss"), $Msg
+    Add-Content -Path $log -Value $line -Encoding utf8
+}
+
+function Show-NetxError([string]$Msg) {
+    Write-LaunchLog "ERROR $Msg"
+    [void][System.Windows.Forms.MessageBox]::Show(
+        $Msg,
+        "NetX",
+        [System.Windows.Forms.MessageBoxButtons]::OK,
+        [System.Windows.Forms.MessageBoxIcon]::Error
+    )
+}
+
+function Ensure-NetxEnv {
+    $envPath = Join-Path $data ".env"
+    if (Test-Path $envPath) { return }
+    Write-LaunchLog "missing .env — running setup_first_run -NonInteractive -DbMode bundled"
+    $setup = Join-Path $PSScriptRoot "setup_first_run.ps1"
+    & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $setup `
+        -ProgramRoot $prog -DataRoot $data -NonInteractive -DbMode bundled
+    if ($LASTEXITCODE -ne 0 -or -not (Test-Path $envPath)) {
+        throw (T `
+            "First-time setup failed. Run Start Menu → NetX → First-time setup.`nLog: $log" `
+            "首次配置失败。请运行「开始菜单 → NetX → First-time setup」。`n日志: $log")
+    }
+}
+
+try {
+    Write-LaunchLog "action=$Action prog=$prog data=$data"
+    switch ($Action) {
+        "setup" {
+            & powershell.exe -NoProfile -ExecutionPolicy Bypass -File (Join-Path $PSScriptRoot "setup_first_run.ps1") `
+                -ProgramRoot $prog -DataRoot $data
+            if ($LASTEXITCODE -ne 0) { throw "setup_exit_$LASTEXITCODE" }
+        }
+        "stop" {
+            & powershell.exe -NoProfile -ExecutionPolicy Bypass -File (Join-Path $PSScriptRoot "stop_netx_app.ps1") `
+                -ProgramRoot $prog -DataRoot $data
+        }
+        "update" {
+            Ensure-NetxEnv
+            & powershell.exe -NoProfile -ExecutionPolicy Bypass -File (Join-Path $PSScriptRoot "check_update.ps1") `
+                -ProgramRoot $prog -DataRoot $data
+        }
+        "start" {
+            Ensure-NetxEnv
+            & powershell.exe -NoProfile -ExecutionPolicy Bypass -File (Join-Path $PSScriptRoot "start_netx_app.ps1") `
+                -ProgramRoot $prog -DataRoot $data
+            if ($LASTEXITCODE -ne 0) { throw "start_exit_$LASTEXITCODE" }
+        }
+        "tray" {
+            Ensure-NetxEnv
+            $trayArgs = @(
+                "-NoProfile", "-ExecutionPolicy", "Bypass",
+                "-File", (Join-Path $PSScriptRoot "netx_tray.ps1"),
+                "-ProgramRoot", $prog, "-DataRoot", $data
+            )
+            if ($StartOnLaunch) { $trayArgs += "-StartOnLaunch" }
+            # Detach tray; keep this process short so Start Menu returns quickly.
+            Start-Process -FilePath "powershell.exe" -ArgumentList $trayArgs -WorkingDirectory $prog -WindowStyle Hidden
+            Start-Sleep -Milliseconds 800
+            [void][System.Windows.Forms.MessageBox]::Show(
+                (T `
+                    "NetX tray started.`nLook for the NetX icon in the system tray (click ^ if hidden).`nUI: http://127.0.0.1:8890/" `
+                    "NetX 托盘已启动。`n请在任务栏右下角找 NetX 图标（被藏起来时点 ^）。`n界面: http://127.0.0.1:8890/"),
+                "NetX",
+                [System.Windows.Forms.MessageBoxButtons]::OK,
+                [System.Windows.Forms.MessageBoxIcon]::Information
+            )
+        }
+    }
+    Write-LaunchLog "action=$Action ok"
+} catch {
+    Show-NetxError ((T "NetX failed to start:`n$($_.Exception.Message)" "NetX 启动失败：`n$($_.Exception.Message)") + "`n`n$log")
+    exit 1
+}

packaging/manifest.example.json

@@ -1,11 +1,11 @@
 {
   "channel": "stable",
-  "latest": "0.4.1",
+  "latest": "0.4.2",
   "min_compatible": "0.3.0",
-  "notes_url": "https://github.com/hansjone/netx/releases/tag/v0.4.1",
+  "notes_url": "https://github.com/hansjone/netx/releases/tag/v0.4.2",
   "windows": {
-    "url": "https://github.com/hansjone/netx/releases/download/v0.4.1/NetX-0.4.1-win64.zip",
-    "setup_url": "https://github.com/hansjone/netx/releases/download/v0.4.1/NetX-Setup-0.4.1.exe",
+    "url": "https://github.com/hansjone/netx/releases/download/v0.4.2/NetX-0.4.2-win64.zip",
+    "setup_url": "https://github.com/hansjone/netx/releases/download/v0.4.2/NetX-Setup-0.4.2.exe",
     "sha256": "",
     "size": 0
   }

packaging/netx_tray.ps1

@@ -35,6 +35,22 @@ if ($autoVal -match '^(1|true|yes|on)$') {
 }
 $uiUrl = "http://${hostBind}:${port}/"
 $ver = Get-NetxVersion -ProgramRoot $prog
+$zh = ([cultureinfo]::CurrentUICulture.Name -match '^(zh|zh-)')
+function T([string]$En, [string]$Zh) {
+    if ($zh) { return $Zh } else { return $En }
+}
+
+if (-not (Test-Path $envPath)) {
+    [void][System.Windows.Forms.MessageBox]::Show(
+        (T `
+            "First-time setup incomplete (missing $envPath).`nRun Start Menu → NetX → First-time setup." `
+            "尚未完成首次配置（缺少 $envPath）。`n请运行「开始菜单 → NetX → First-time setup」。"),
+        "NetX",
+        [System.Windows.Forms.MessageBoxButtons]::OK,
+        [System.Windows.Forms.MessageBoxIcon]::Warning
+    )
+    exit 1
+}
 
 $startPs1 = Join-Path $PSScriptRoot "start_netx_app.ps1"
 $stopPs1 = Join-Path $PSScriptRoot "stop_netx_app.ps1"
@@ -56,11 +72,6 @@ $form.WindowState = "Minimized"
 $form.Visible = $false
 $form.Size = New-Object System.Drawing.Size(0, 0)
 
-$zh = ([cultureinfo]::CurrentUICulture.Name -match '^(zh|zh-)')
-function T([string]$En, [string]$Zh) {
-    if ($zh) { return $Zh } else { return $En }
-}
-
 $notify = New-Object System.Windows.Forms.NotifyIcon
 $notify.Text = "NetX $ver"
 $notify.Visible = $true

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "netx-ops"
-version = "0.4.1"
+version = "0.4.2"
 description = "netx operations tool: alarm-centric workflows with REST API and stdio MCP"
 readme = "README.md"
 requires-python = ">=3.11"