fix(stage-tamagotchi): harden cross-platform auto-updater flow, diagnostics, logs, and cache cleanup (#1566)

Author: jensenhuangfan

apps/stage-tamagotchi/electron-builder.config.ts

@@ -101,6 +101,16 @@ export default {
   },
   win: {
     executableName: 'airi',
+    // NOTICE: Keep `channel: 'latest-${arch}'` for architecture-aware updater metadata.
+    // electron-builder expands `${arch}` at publish-time (for example: `latest-x64`, `latest-arm64`),
+    // and electron-updater later consumes that expanded channel to resolve platform-specific *.yml files.
+    // This prevents cross-arch lookups such as arm64 clients reading x64 metadata.
+    publish: {
+      provider: 'github',
+      owner: 'moeru-ai',
+      repo: 'airi',
+      channel: 'latest-${arch}',
+    },
   },
   nsis: {
     artifactName: '${productName}-${version}-windows-${arch}-setup.${ext}',
@@ -113,6 +123,76 @@ export default {
   },
   mac: {
     entitlementsInherit: 'build/entitlements.mac.plist',
+    // NOTICE: Same channel rule as Windows. Keep `${arch}` here so generated metadata resolves
+    // to architecture-specific update feeds on macOS (for example: `latest-x64-mac.yml`, `latest-arm64-mac.yml`).
+    publish: {
+      provider: 'github',
+      owner: 'moeru-ai',
+      repo: 'airi',
+      // NOTICE: `channel: 'latest-${arch}'` matters because electron-builder expands
+      // `${arch}` before it writes any publish metadata, and electron-updater later
+      // reuses that expanded channel string when deciding which `*.yml` file to fetch.
+      //
+      // Without this, the updater would look for `latest-mac.yml` for both x64 and arm64 macOS builds,
+      // which means the x64 build would be used for arm64 (Apple Silicon) users, causing suboptimal performance and higher resource usage. By embedding `${arch}`
+      // into the channel name, we ensure that the updater looks for `latest-x64-mac.yml` and `latest-arm64-mac.yml` respectively.
+      //
+      // This is how channel name was constructed:
+      //
+      // 1. `expandPublishConfig(...)` expands string values in the publish config.
+      //    That is where `latest-${arch}` becomes `latest-x64` or `latest-arm64`.
+      //    https://github.com/electron-userland/electron-builder/blob/ed422f36540a93e9bd2a19bc7a5e729bf2b033ea/packages/app-builder-lib/src/publish/PublishManager.ts#L521-L532
+      //
+      // 2. The expanded publish config is written into `app-update.yml`.
+      //    The packaged app therefore carries `channel: latest-x64` or
+      //    `channel: latest-arm64`, not the literal template string.
+      //    https://github.com/electron-userland/electron-builder/blob/ed422f36540a93e9bd2a19bc7a5e729bf2b033ea/packages/app-builder-lib/src/publish/PublishManager.ts#L93-L96
+      //
+      // 3. electron-builder also uses that expanded channel when generating update
+      //    metadata files. `getUpdateInfoFileName(channel, packager, arch)` builds the
+      //    filename as:
+      //      `${channel}${osSuffix}${getArchPrefixForUpdateFile(arch, packager)}.yml`
+      //    https://github.com/electron-userland/electron-builder/blob/ed422f36540a93e9bd2a19bc7a5e729bf2b033ea/packages/app-builder-lib/src/publish/updateInfoBuilder.ts#L65-L68
+      //
+      // 4. For macOS, `osSuffix` is `-mac` and `getArchPrefixForUpdateFile(...)`
+      //    returns an empty string. So:
+      //      `latest-x64`   -> `latest-x64-mac.yml`
+      //      `latest-arm64` -> `latest-arm64-mac.yml`
+      //    This is the publish-time side of the behavior.
+      //
+      // 5. At runtime, electron-updater reads the embedded `app-update.yml` and takes
+      //    its `channel` value. It does not reconstruct `latest-${arch}` itself; it
+      //    consumes the already-expanded value from step 2.
+      //
+      // 6. `Provider.getChannelFilePrefix()` appends the platform suffix:
+      //    - macOS -> `-mac`
+      //    - Windows -> ``
+      //    - Linux x64 -> `-linux`
+      //    - Linux non-x64 -> `-linux-${arch}`
+      //    https://github.com/electron-userland/electron-builder/blob/ed422f36540a93e9bd2a19bc7a5e729bf2b033ea/packages/electron-updater/src/providers/Provider.ts#L44-L52
+      //
+      // 7. `getCustomChannelName(channel)` then returns:
+      //      `${channel}${this.getChannelFilePrefix()}`
+      //    So the updater turns:
+      //      `latest-x64`   -> `latest-x64-mac`
+      //      `latest-arm64` -> `latest-arm64-mac`
+      //    https://github.com/electron-userland/electron-builder/blob/ed422f36540a93e9bd2a19bc7a5e729bf2b033ea/packages/electron-updater/src/providers/Provider.ts#L58-L60
+      //
+      // 8. GitHubProvider passes that channel name into `getChannelFilename(channel)`,
+      //    which simply appends `.yml`, so the final lookup becomes:
+      //      `latest-x64-mac.yml`
+      //      `latest-arm64-mac.yml`
+      //    https://github.com/electron-userland/electron-builder/blob/ed422f36540a93e9bd2a19bc7a5e729bf2b033ea/packages/electron-updater/src/util.ts#L27-L29
+      //    https://github.com/electron-userland/electron-builder/blob/ed422f36540a93e9bd2a19bc7a5e729bf2b033ea/packages/electron-updater/src/providers/GitHubProvider.ts#L132-L145
+      //
+      // Resulting filenames with this config:
+      // - macOS x64 -> `latest-x64-mac.yml`
+      // - macOS arm64 -> `latest-arm64-mac.yml`
+      // - Windows x64 -> `latest-x64.yml`
+      // - Linux x64 -> `latest-x64-linux.yml`
+      // - Linux arm64 -> `latest-arm64-linux-arm64.yml`
+      channel: 'latest-${arch}',
+    },
     extendInfo: [
       {
         NSMicrophoneUsageDescription: 'AIRI requires microphone access for voice interaction',
@@ -140,6 +220,13 @@ export default {
       'deb',
       'rpm',
     ],
+    // NOTICE: Same channel rule as Windows/macOS. Keep `${arch}` to avoid x64/arm64 feed collisions on Linux.
+    publish: {
+      provider: 'github',
+      owner: 'moeru-ai',
+      repo: 'airi',
+      channel: 'latest-${arch}',
+    },
     category: 'Utility',
     synopsis: 'AI VTuber/Waifu chatbot app inspired by Neuro-sama.',
     description: 'AIRI is an AI VTuber/Waifu chatbot supporting Live2D/VRM avatars, featuring human-like interactions and modular stage-based rendering.',
@@ -151,72 +238,5 @@ export default {
     artifactName: '${productName}-${version}-linux-${arch}.${ext}',
   },
   npmRebuild: false,
-  publish: {
-    provider: 'github',
-    owner: 'moeru-ai',
-    repo: 'airi',
-    // NOTICE: `channel: 'latest-${arch}'` matters because electron-builder expands
-    // `${arch}` before it writes any publish metadata, and electron-updater later
-    // reuses that expanded channel string when deciding which `*.yml` file to fetch.
-    //
-    // Without this, the updater would look for `latest-mac.yml` for both x64 and arm64 macOS builds,
-    // which means the x64 build would be used for arm64 (Apple Silicon) users, causing suboptimal performance and higher resource usage. By embedding `${arch}`
-    // into the channel name, we ensure that the updater looks for `latest-x64-mac.yml` and `latest-arm64-mac.yml` respectively.
-    //
-    // This is how channel name was constructed:
-    //
-    // 1. `expandPublishConfig(...)` expands string values in the publish config.
-    //    That is where `latest-${arch}` becomes `latest-x64` or `latest-arm64`.
-    //    https://github.com/electron-userland/electron-builder/blob/ed422f36540a93e9bd2a19bc7a5e729bf2b033ea/packages/app-builder-lib/src/publish/PublishManager.ts#L521-L532
-    //
-    // 2. The expanded publish config is written into `app-update.yml`.
-    //    The packaged app therefore carries `channel: latest-x64` or
-    //    `channel: latest-arm64`, not the literal template string.
-    //    https://github.com/electron-userland/electron-builder/blob/ed422f36540a93e9bd2a19bc7a5e729bf2b033ea/packages/app-builder-lib/src/publish/PublishManager.ts#L93-L96
-    //
-    // 3. electron-builder also uses that expanded channel when generating update
-    //    metadata files. `getUpdateInfoFileName(channel, packager, arch)` builds the
-    //    filename as:
-    //      `${channel}${osSuffix}${getArchPrefixForUpdateFile(arch, packager)}.yml`
-    //    https://github.com/electron-userland/electron-builder/blob/ed422f36540a93e9bd2a19bc7a5e729bf2b033ea/packages/app-builder-lib/src/publish/updateInfoBuilder.ts#L65-L68
-    //
-    // 4. For macOS, `osSuffix` is `-mac` and `getArchPrefixForUpdateFile(...)`
-    //    returns an empty string. So:
-    //      `latest-x64`   -> `latest-x64-mac.yml`
-    //      `latest-arm64` -> `latest-arm64-mac.yml`
-    //    This is the publish-time side of the behavior.
-    //
-    // 5. At runtime, electron-updater reads the embedded `app-update.yml` and takes
-    //    its `channel` value. It does not reconstruct `latest-${arch}` itself; it
-    //    consumes the already-expanded value from step 2.
-    //
-    // 6. `Provider.getChannelFilePrefix()` appends the platform suffix:
-    //    - macOS -> `-mac`
-    //    - Windows -> ``
-    //    - Linux x64 -> `-linux`
-    //    - Linux non-x64 -> `-linux-${arch}`
-    //    https://github.com/electron-userland/electron-builder/blob/ed422f36540a93e9bd2a19bc7a5e729bf2b033ea/packages/electron-updater/src/providers/Provider.ts#L44-L52
-    //
-    // 7. `getCustomChannelName(channel)` then returns:
-    //      `${channel}${this.getChannelFilePrefix()}`
-    //    So the updater turns:
-    //      `latest-x64`   -> `latest-x64-mac`
-    //      `latest-arm64` -> `latest-arm64-mac`
-    //    https://github.com/electron-userland/electron-builder/blob/ed422f36540a93e9bd2a19bc7a5e729bf2b033ea/packages/electron-updater/src/providers/Provider.ts#L58-L60
-    //
-    // 8. GitHubProvider passes that channel name into `getChannelFilename(channel)`,
-    //    which simply appends `.yml`, so the final lookup becomes:
-    //      `latest-x64-mac.yml`
-    //      `latest-arm64-mac.yml`
-    //    https://github.com/electron-userland/electron-builder/blob/ed422f36540a93e9bd2a19bc7a5e729bf2b033ea/packages/electron-updater/src/util.ts#L27-L29
-    //    https://github.com/electron-userland/electron-builder/blob/ed422f36540a93e9bd2a19bc7a5e729bf2b033ea/packages/electron-updater/src/providers/GitHubProvider.ts#L132-L145
-    //
-    // Resulting filenames with this config:
-    // - macOS x64 -> `latest-x64-mac.yml`
-    // - macOS arm64 -> `latest-arm64-mac.yml`
-    // - Windows x64 -> `latest-x64.yml`
-    // - Linux x64 -> `latest-x64-linux.yml`
-    // - Linux arm64 -> `latest-arm64-linux-arm64.yml`
-    channel: 'latest-${arch}',
-  },
+
 } satisfies Configuration

apps/stage-tamagotchi/package.json

@@ -29,7 +29,9 @@
     "rename-artifacts": "mkdir -p bundle && tsx scripts/rename-artifacts.ts",
     "merge-latest-mac": "tsx scripts/merge-latest-mac.ts",
     "regenerate-windows-latest": "tsx scripts/regenerate-windows-latest.ts",
-    "artifacts-metadata": "tsx scripts/artifacts-metadata.ts"
+    "artifacts-metadata": "tsx scripts/artifacts-metadata.ts",
+    "update-test:generate": "tsx scripts/update-test/generate-manifest.ts",
+    "update-test:server": "tsx scripts/update-test/start-server.ts"
   },
   "dependencies": {
     "@date-fns/utc": "^2.1.1",

apps/stage-tamagotchi/scripts/update-test/README.md

@@ -0,0 +1,85 @@
+# AIRI Electron Updater Local Test Harness
+
+This directory provides a local mocked update-server workflow for Stage Tamagotchi.
+
+It is intended to verify AIRI's refactored updater path:
+
+- explicit `UPDATE_SERVER_URL` override mode
+- no GitHub Releases API dependency
+- no custom updater cache ownership
+- developer-only updater diagnostics inspection
+
+## Files
+
+- `generate-manifest.ts`: generate local `latest-*.yml` metadata and placeholder artifacts
+- `start-server.ts`: serve generated fixtures over HTTP
+- `setup.sh`: prepare the local fixture directories
+- `run-test.sh`: thin orchestration wrapper
+- `dev-app-update.local.yml`: optional generic-provider template for development-only experiments
+
+## Quick Start
+
+From the repo root:
+
+```bash
+bash apps/stage-tamagotchi/scripts/update-test/setup.sh
+pnpm -F @proj-airi/stage-tamagotchi update-test:generate \
+  --root scripts/update-test/fixtures/server \
+  --channel stable \
+  --target aarch64-apple-darwin \
+  --version 9.9.9-update-test.1
+pnpm -F @proj-airi/stage-tamagotchi update-test:server \
+  --port 8787 \
+  --root scripts/update-test/fixtures/server
+```
+
+Then, in another terminal:
+
+```bash
+cd apps/stage-tamagotchi
+UPDATE_SERVER_URL=http://127.0.0.1:8787/stable pnpm run dev
+```
+
+## Verification Flow
+
+1. Open the About page.
+2. Click `Check for updates`.
+3. Confirm the update becomes available.
+4. Click `Download update`.
+5. Confirm the updater reaches the `downloaded` state.
+6. Open `Settings > System > Developer`.
+7. Enable `Inspect updater diagnostics`.
+8. Open `Devtools > Updater`.
+9. Confirm:
+   - `overrideActive=true`
+   - `feedUrl` points to `http://127.0.0.1:8787/stable`
+   - `platform`, `arch`, and `channel` match the current runtime
+
+## Helper Wrapper
+
+You can also print the workflow commands with:
+
+```bash
+bash apps/stage-tamagotchi/scripts/update-test/run-test.sh
+```
+
+Environment variables supported by the wrapper:
+
+- `PORT`
+- `CHANNEL`
+- `TARGET`
+- `VERSION`
+
+Common targets:
+
+- Apple Silicon macOS: `aarch64-apple-darwin`
+- Intel macOS: `x86_64-apple-darwin`
+- Windows x64: `x86_64-pc-windows-msvc`
+- Linux x64: `x86_64-unknown-linux-gnu`
+
+## Notes
+
+- The generated artifact is a placeholder file meant for update discovery and early download flow verification.
+- Real signed installer execution remains a separate manual verification step.
+- The first pass is manual-first by design. A Playwright `_electron` smoke layer can be added on top later.
+- When invoking the package scripts through `pnpm -F @proj-airi/stage-tamagotchi`, treat `--root` as relative to `apps/stage-tamagotchi`, not the workspace root.

apps/stage-tamagotchi/scripts/update-test/fixtures/server/stable/AIRI-9.9.9-update-test.1-darwin-arm64.dmg

@@ -0,0 +1 @@
+mock-update-stable-9.9.9-update-test.1

apps/stage-tamagotchi/scripts/update-test/fixtures/server/stable/AIRI-9.9.9-update-test.1-windows-x64-setup.exe

@@ -0,0 +1 @@
+mock-update-stable-9.9.9-update-test.1

apps/stage-tamagotchi/scripts/update-test/fixtures/server/stable/latest-arm64-mac.yml

@@ -0,0 +1,9 @@
+version: 9.9.9-update-test.1
+files:
+  - url: AIRI-9.9.9-update-test.1-darwin-arm64.dmg
+    sha512: D6msk0IrWPMUcpjWnMZfEVrY8Qe/yQN4iJO6O6mttkwl5pENCNazyxdvRJX+kOZFujznbCIc+m1z6dokPzHg2A==
+    size: 38
+path: AIRI-9.9.9-update-test.1-darwin-arm64.dmg
+sha512: D6msk0IrWPMUcpjWnMZfEVrY8Qe/yQN4iJO6O6mttkwl5pENCNazyxdvRJX+kOZFujznbCIc+m1z6dokPzHg2A==
+releaseDate: 2026-04-05T17:39:00.050Z
+releaseNotes: Mock update for AIRI local updater verification.

apps/stage-tamagotchi/scripts/update-test/fixtures/server/stable/latest-x64.yml

@@ -0,0 +1,9 @@
+version: 9.9.9-update-test.1
+files:
+  - url: AIRI-9.9.9-update-test.1-windows-x64-setup.exe
+    sha512: D6msk0IrWPMUcpjWnMZfEVrY8Qe/yQN4iJO6O6mttkwl5pENCNazyxdvRJX+kOZFujznbCIc+m1z6dokPzHg2A==
+    size: 38
+path: AIRI-9.9.9-update-test.1-windows-x64-setup.exe
+sha512: D6msk0IrWPMUcpjWnMZfEVrY8Qe/yQN4iJO6O6mttkwl5pENCNazyxdvRJX+kOZFujznbCIc+m1z6dokPzHg2A==
+releaseDate: 2026-04-05T14:51:10.149Z
+releaseNotes: Mock update for AIRI local updater verification.

apps/stage-tamagotchi/scripts/update-test/generate-manifest.test.ts

@@ -0,0 +1,63 @@
+import { mkdtemp, readFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { afterEach, describe, expect, it } from 'vitest'
+
+import * as yaml from 'yaml'
+
+import { generateManifestFixtures, resolveLatestFilenameForTarget } from './generate-manifest'
+
+describe('generateManifestFixtures', () => {
+  const roots: string[] = []
+
+  afterEach(async () => {
+    await Promise.all(roots.map(async (root) => {
+      await import('node:fs/promises').then(({ rm }) => rm(root, { recursive: true, force: true }))
+    }))
+    roots.length = 0
+  })
+
+  it('maps targets to the expected latest-yml filenames', () => {
+    expect(resolveLatestFilenameForTarget('x86_64-pc-windows-msvc')).toBe('latest-x64.yml')
+    expect(resolveLatestFilenameForTarget('aarch64-apple-darwin')).toBe('latest-arm64-mac.yml')
+    expect(resolveLatestFilenameForTarget('x86_64-apple-darwin')).toBe('latest-x64-mac.yml')
+    expect(resolveLatestFilenameForTarget('x86_64-unknown-linux-gnu')).toBe('latest-x64-linux.yml')
+    expect(resolveLatestFilenameForTarget('aarch64-unknown-linux-gnu')).toBe('latest-arm64-linux-arm64.yml')
+  })
+
+  it('generates a channel directory, manifest, and placeholder artifact', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'airi-update-test-'))
+    roots.push(root)
+
+    const result = await generateManifestFixtures({
+      rootDir: root,
+      channel: 'stable',
+      target: 'x86_64-pc-windows-msvc',
+      version: '9.9.9-test.1',
+      releaseNotes: 'Mock update for AIRI local updater verification.',
+      artifactContent: 'mock-installer-binary',
+    })
+
+    expect(result.channelDir).toBe(join(root, 'stable'))
+    expect(result.latestFilename).toBe('latest-x64.yml')
+    expect(result.artifactFilename).toBe('AIRI-9.9.9-test.1-windows-x64-setup.exe')
+
+    const manifest = yaml.parse(await readFile(result.manifestPath, 'utf8'))
+    expect(manifest).toMatchObject({
+      version: '9.9.9-test.1',
+      path: 'AIRI-9.9.9-test.1-windows-x64-setup.exe',
+      releaseNotes: 'Mock update for AIRI local updater verification.',
+      files: [
+        {
+          url: 'AIRI-9.9.9-test.1-windows-x64-setup.exe',
+        },
+      ],
+    })
+
+    expect(typeof manifest.sha512).toBe('string')
+    expect(typeof manifest.releaseDate).toBe('string')
+    expect(manifest.files[0]?.size).toBeGreaterThan(0)
+    await expect(readFile(result.artifactPath, 'utf8')).resolves.toBe('mock-installer-binary')
+  })
+})