feat(linux): add standard AppImage update metadata

[satwiksharma01]

Summary

AppImages currently have no standard update information or .zsync asset for external AppImage tools. Fill the runtime's reserved .upd_info section and generate a matching .zsync after packaging, then upload both files in the Linux release job.

The completion hook removes the previous embedded blockmap before changing the runtime, rebuilds it, and replaces event.updateInfo before electron-builder schedules the update feed and publication. This preserves electron-updater's differential updates and prevents stale hashes in latest-linux.yml. It works with the existing legacy runtime and the static runtime proposed in #1070; this PR does not depend on that runtime change.

Stable builds discover upstream releases through gh-releases-zsync|...|latest. RC builds generate a sidecar with its explicit tagged URL but leave external discovery empty: AppImageUpdate's latest-all can select a helper-only prerelease without an AppImage asset. Their existing electron-updater path stays available. CI verifies the stable/RC metadata policy and the sidecar's existence. The packaging documentation explains the local zsync requirement and the builder helper compatibility check.

Related issue

Refs #734

Type of change

• Enhancement

Release impact

• Minor

Desktop impact

• Linux
• Installer / packaging

Screenshots / video

Packaging change; no UI changes.

Testing

• 14 focused tests verify ELF32/ELF64 payload preservation, updated SHA512 and actual BLAKE2 block checksums, stable/RC policy, tagged URLs, unrelated targets and validation failures before mutation.
• Both TypeScript checks, full lint and docs check pass (26 existing lint warnings).
• Full unit suite passes: 309 files, 4,319 tests passed, 5 skipped. Vite production builds pass for the renderer and Electron main/preload bundles.
• Builder schema, named hook resolution and workflow YAML parsing pass against electron-builder/app-builder-lib 26.15.3.
• Real Linux integration of the repository hook with the Packager event lifecycle and feed writer passes for legacy/static runtimes, stable and RC. Generated sidecar SHA1/length match the final artifact; every embedded block checksum matches. Both runtimes return the expected update information with exit 0, including the intentionally empty RC value.
• Tiny static stable/RC payloads launch through real FUSE mounts; the legacy stable payload launches through extraction. Full packaged OpenScreen and live external GitHub discovery/download were not tested. A local zsync reconstruction passed on an identical static payload/checksum body; no remote delta-download claim is made.

The hook uses the internal appendBlockmap helper to retain the builder's existing format. Its return shape and event ordering must be rechecked when upgrading builder; the source and docs call this out.

Checks use the repository's pinned Node 22.22.1 and npm 10.9.4. This is an AI-assisted contribution.

Summary by CodeRabbit

• New Features
  • Linux AppImages now support incremental updates through the stable release feed, which can reduce the amount downloaded for an update.
  • Release downloads include zsync update files for AppImages. Prerelease updates continue through the existing update process.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 0903aca8-7026-4654-a086-753513d71121

📥 Commits

Reviewing files that changed from the base of the PR and between 870196c and b74f5fc.

📒 Files selected for processing (5)

• .github/workflows/build.yml
• electron-builder.json5
• scripts/appimage-updates.cjs
• scripts/appimage-updates.test.mjs
• technical-documentation/engineering/build-and-packaging.md

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 6 remain after this review.

---

📝 Walkthrough

Walkthrough

Build hooks now update AppImage update metadata and generate versioned .zsync sidecars. Linux packaging validates stable and prerelease update information and uploads the sidecars.

Changes

AppImage updates

Layer / File(s)	Summary
AppImage metadata and sidecar generation electron-builder.json5, scripts/appimage-updates.cjs, scripts/appimage-updates.test.mjs	Build hooks update .upd_info, rebuild the blockmap, and create versioned .zsync sidecars. Tests cover ELF32 and ELF64 artifacts, stable and prerelease metadata, invalid inputs, and unrelated artifacts.
Linux validation and publishing .github/workflows/build.yml, technical-documentation/engineering/build-and-packaging.md	Linux packaging installs zsync, checks sidecar and update-information values, and uploads sidecars. Documentation describes the stable and prerelease policies.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant electron-builder
  participant artifactBuildCompleted
  participant AppImage
  participant zsyncmake
  participant afterAllArtifactBuild
  participant Linux workflow
  electron-builder->>artifactBuildCompleted: AppImage build event
  artifactBuildCompleted->>AppImage: Rewrite .upd_info and blockmap
  artifactBuildCompleted->>zsyncmake: Generate versioned .zsync sidecar
  electron-builder->>afterAllArtifactBuild: Artifact paths
  afterAllArtifactBuild-->>electron-builder: .zsync paths
  Linux workflow->>Linux workflow: Validate and upload sidecars

Loading

Merge Risk: ⚪ Minimal · up to b74f5

This change adds standard AppImage update metadata and zsync sidecars for Linux releases. No concrete merge-blocking risk was found. When electron-builder is upgraded, recheck the internal helper the hook relies on.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 2 files. (3 skipped: 3…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the primary change: adding standard AppImage update metadata for Linux.
Description check	✅ Passed	The description includes all required sections and provides clear details about the change, related issue, release and platform impact, testing, and the absence of UI changes.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 2 files. (3 skipped: 3 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[EtienneLescot]

Reviewed line by line (build.yml + scripts): zsync from apt, no secrets, no third-party action, execFileSync without a shell; electron-updater metadata keeps the final hashes. Will be exercised by a dispatched build before the next RC. Thanks @satwiksharma01!