Prepare Windows in-app updater debug release path.

Document the zip-sidecar troubleshooting flow, add a quick menu action to open updater data/log storage, and bump the app version for reproducible update testing.

Made-with: Cursor

Author: staindart

README.md

@@ -24,7 +24,7 @@ All core materials are available publicly for currently active https://www.hyper
 - [`api`](./api) - backend API handlers and server-side endpoints.
 - [`blockchain`](./blockchain) - TON/blockchain interaction logic and related helpers.
 - [`telegram`](./telegram) - Telegram-specific integration utilities and adapters.
-- [`windows`](./windows) - Electron desktop shell, NSIS installer config, and auto-update flow.
+- [`windows`](./windows) - Electron desktop shell, NSIS installer config, and auto-update flow. Troubleshooting in-app updates: [texts/windows-in-app-updater-debug.md](./texts/windows-in-app-updater-debug.md).
 - [`scripts`](./scripts) - developer/ops scripts (local run, migration, release helpers).
 - [`docs`](./docs) - project and operational documentation (architecture, releases, security reference, tooling).
 - [`research`](./research) - exploratory notes, investigations, and proposals not yet promoted to `docs/`.

backlogs/short_term_backlog.md

@@ -1,3 +1,4 @@
+Home on Windowd did not display after the update
 Login screen
 Dealing with pool count
 Updates on launch test

package-lock.json

@@ -16,7 +16,7 @@
     "url": "https://github.com/HyperlinksSpace/HyperlinksSpaceProgram.git"
   },
   "main": "index.js",
-  "version": "53.0.1391",
+  "version": "53.0.1392",
   "type": "module",
   "engines": {
     "node": ">=18 <=22"

package.json

@@ -0,0 +1,51 @@
+# Windows in-app updater: debugging failed “quick update”
+
+The packaged Windows app uses a **custom zip sidecar** path in `windows/build.cjs`. The in-app **“Update with reload”** flow stages a **portable ZIP** from GitHub, unpacks it under user data, then applies it with a helper script. It does **not** use the NSIS `.exe` download from `electron-updater`’s `update-downloaded` event on Windows (that event is ignored when the zip path is active).
+
+If the UI still behaves like an old build after you used the updater dialog, use the sections below.
+
+## 1. Log and data locations (on your PC)
+
+All paths are under Electron **`app.getPath("userData")`**. On Windows this is usually:
+
+`%APPDATA%\<app-specific folder>\`
+
+For this product, the folder name typically matches the install branding (e.g. **Hyperlinks Space Program**). Exact path: use **Updates → Open update data folder…** in the app menu (opens the folder in Explorer).
+
+| File / folder | Purpose |
+|---------------|---------|
+| **`main.log`** | General main-process log; lines tagged **`[updater:…]`** mirror structured updater diagnostics. |
+| **`hsp-update-apply.log`** | Append-only log when you click **Update with reload** and the staged zip apply runs (spawn, plan, errors). |
+| **`pending-update-versions\`** | Staged unpacked builds per version (`<version>\extract\…`). If a version folder exists with a valid main `.exe`, the dialog can offer install. |
+| **`%TEMP%\hsp-update-plan-*.json`** | Short-lived apply plan (timestamped). |
+| **`%TEMP%\hsp-apply-versions-*.ps1`** | Short-lived PowerShell helper for apply. |
+| **`%TEMP%\hsp-apply-trace.log`** | Launcher trace written before the inner apply script runs. |
+
+The **Updater** window also shows a rolling activity log (last lines only); for deep investigation, prefer **`main.log`** and **`hsp-update-apply.log`**.
+
+### What to search for in `main.log`
+
+- `[updater:prepare] FAILED` — zip download, verify, or unpack failed.
+- `update-downloaded: ignored on Windows` — expected: NSIS installer finished downloading but Windows uses the zip pipeline instead.
+- `requestInstallNow blocked: no staged build` — UI offered reload before staging completed, or staging was cleared; check `pending-update-versions` and zip assets on GitHub.
+
+## 2. GitHub release assets (maintainers)
+
+The sidecar resolver (`resolveWindowsZipSidecarMeta` in `windows/build.cjs`) expects:
+
+1. **`latest.yml`** — on the release (electron-updater feed; gives the target version).
+2. **Portable zip** whose name matches the convention: **`<productSlug>_<version>.zip`** (e.g. `HyperlinksSpaceProgram_1.2.3.zip`). The slug comes from `package.json` `build.productName` (spaces removed); see `windows/product-brand.cjs` (`portableZipPrefix`).
+3. **`zip-latest.yml`** (optional but recommended) — produced by the Windows cleanup script; includes **`sha512`** for the zip so the client can verify before unpack.
+
+Repository used for the feed: **`HyperlinksSpace/HyperlinksSpaceProgram`** (see `UPDATE_GITHUB_OWNER` / `UPDATE_GITHUB_REPO` in `windows/build.cjs`).
+
+If **`zip-latest.yml`** is missing or incomplete, the client falls back to **`latest.yml` + inferred zip name** (`<portableZipPrefix><version>.zip`). If that zip is missing or 404, prepare fails and the old build keeps running.
+
+## 3. When a full `.exe` installer fixes it
+
+Installing from a **new NSIS `.exe`** replaces the whole install tree. That bypasses any broken zip staging or apply step, which is why “download new installer” can succeed when the inner dialog did not fully apply an update.
+
+## 4. Related code
+
+- `windows/build.cjs` — `setupAutoUpdater`, `tryBeginVersionsPrepare`, `requestInstallNow`, `applyVersionsStagedUpdate`.
+- `windows/cleanup.cjs` — generating **`zip-latest.yml`** for releases.

texts/windows-in-app-updater-debug.md

@@ -9,6 +9,7 @@ const {
   ipcMain,
   nativeImage,
   nativeTheme,
+  shell,
 } = require("electron");
 
 /** Must match package.json `build.appId`. Call synchronously before `ready` on Windows (Electron + shell taskbar expectations). */
@@ -1831,6 +1832,22 @@ function setupAppMenu() {
             }
           },
         },
+        { type: "separator" },
+        {
+          label: "Open update data folder…",
+          click: () => {
+            const dir = app.getPath("userData");
+            void shell.openPath(dir).then((err) => {
+              if (err) {
+                void dialog.showMessageBox({
+                  type: "error",
+                  title: "Could not open folder",
+                  message: err,
+                });
+              }
+            });
+          },
+        },
       ],
     },
   ];