Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(desktop): Linux packages ship an asar with no node_modules — app cannot start (#3063)

mike-inkeep0575704d5357
diff --git a/.changeset/linux-package-missing-node-modules.md b/.changeset/linux-package-missing-node-modules.md
new file mode 100644
index 000000000..321498cc0
--- /dev/null
+++ b/.changeset/linux-package-missing-node-modules.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Fixed the Linux desktop packages (`.deb` and AppImage), which installed successfully and then failed to start. Launching the app did nothing at all — no window, no error dialog — because the packaged bundle was built without its runtime dependencies, so the app exited on its first import before it could show anything. Linux packages now ship their dependencies and launch normally. macOS and Windows builds were never affected.
diff --git a/.github/workflows/desktop-build-win-linux.yml b/.github/workflows/desktop-build-win-linux.yml
index fa76caaa7..e5a37188e 100644
--- a/.github/workflows/desktop-build-win-linux.yml
+++ b/.github/workflows/desktop-build-win-linux.yml
@@ -245,6 +245,14 @@ jobs:
fi
pnpm exec electron-builder --win --publish never "${extra[@]}"
+ # Fail before uploading an installer that cannot start. An asar packed
+ # without `node_modules` produces a binary that dies on its first bare
+ # import, before `app.ready` — no window, no dialog — so an operator
+ # downloading this artifact for QA would see only "nothing happens".
+ - name: Assert the packaged asar carries its dependencies
+ working-directory: packages/desktop
+ run: node scripts/assert-asar-complete.mjs dist-desktop "windows installers"
+
# One artifact per installer, each named for the file it carries, so the
# operator downloads only the arch they're about to QA instead of pulling
# both installers plus metadata as one blob. GitHub zips every artifact on
@@ -283,7 +291,7 @@ jobs:
# Two cells, each on a NATIVE runner for its arch. Cross-compiling the arm64
# native deps from an x64 host is impractical (pnpm installs only the
# host-matching `@parcel/watcher-*` prebuild, and the Linux build skips
- # @electron/rebuild by design — see electron-builder.yml `beforeBuild`), so
+ # @electron/rebuild by design — see electron-builder.linux.yml), so
# the arm64 deb is built on GitHub's arm64 Linux runner where pnpm installs
# the arm64 prebuilds directly and `scripts/stage-parcel-watcher.mjs` stages
# the right binary.
@@ -371,7 +379,20 @@ jobs:
# emulation or system fpm is involved.
- name: Package ${{ matrix.targets }}
working-directory: packages/desktop
- run: pnpm exec electron-builder --linux ${{ matrix.targets }} --publish never
+ # --config: the Linux overlay turns off the native-rebuild pass WITHOUT
+ # asserting that node_modules are staged externally. See
+ # electron-builder.linux.yml.
+ run: |
+ pnpm exec electron-builder --linux ${{ matrix.targets }} --publish never \
+ --config electron-builder.linux.yml
+
+ # Fail before uploading an installer that cannot start (see the Windows
+ # step for the full rationale). This is the control that would have caught
+ # the 0.42.2 arm64 deb, which installed cleanly and then died on
+ # `Cannot find package 'pino'` with no user-visible signal at all.
+ - name: Assert the packaged asar carries its dependencies
+ working-directory: packages/desktop
+ run: node scripts/assert-asar-complete.mjs dist-desktop "linux ${{ matrix.arch }} installers"
# One artifact per installer, named for its file (see the Windows upload
# steps for the rationale). Guarded per-arch because artifact names must
diff --git a/packages/desktop/electron-builder.linux.yml b/packages/desktop/electron-builder.linux.yml
new file mode 100644
index 000000000..95868aeb3
--- /dev/null
+++ b/packages/desktop/electron-builder.linux.yml
@@ -0,0 +1,38 @@
+# Linux packaging config. Inherits everything from `electron-builder.yml` and
+# changes exactly one thing: it turns off electron-builder's native-rebuild pass.
+#
+# WHY THIS FILE EXISTS, rather than a `beforeBuild` hook returning false.
+#
+# The rebuild has to be skipped on Linux: the only modules @electron/rebuild
+# finds to compile are unused node-gyp transitive deps pulled in through the
+# bundled server (`node-liblzma` via `just-bash`, `@mongodb-js/zstd`). pnpm
+# ignores their build scripts, so they are unbuilt in every normal install and
+# the app already runs without them — but node-liblzma's binding.gyp forces
+# `-Werror`, and Electron's bundled v8 headers trip `-Wcomment` under GCC, so
+# the pass hard-fails. Every native module that actually ships on Linux
+# (@napi-rs/keyring, @inkeep/open-knowledge-native-config, @parcel/watcher) is
+# N-API and loads straight from its prebuilt `.node`.
+#
+# The obvious way to express that — a `beforeBuild` hook returning `false` —
+# does something else as well, and the difference shipped a broken package.
+# In app-builder-lib, `beforeBuild` resolving to `false` means "I am staging
+# node_modules myself":
+#
+# this._nodeModulesHandledExternally = !performDependenciesInstallOrRebuild
+#
+# and that flag gates the ONLY code path that copies dependencies into the app
+# (`computeNodeModuleFileSets`). Nothing was staging them, so the Linux asar
+# shipped with no `node_modules` at all and the app died on its first bare
+# import — before `app.ready`, so with no window, no dialog and no crash report.
+#
+# `npmRebuild: false` returns a few lines EARLIER in the same function, before
+# that flag is ever set, so it skips the rebuild while still shipping the
+# dependencies. It is a top-level-only option (not per-platform), which is why
+# it lives in a Linux-only overlay instead of in the shared config.
+#
+# Linux builds MUST pass `--config electron-builder.linux.yml`. Forgetting it
+# fails the build loudly on node-liblzma rather than producing a silently
+# broken package, which is the failure mode this file is here to prevent.
+extends: file:./electron-builder.yml
+
+npmRebuild: false
diff --git a/packages/desktop/electron-builder.yml b/packages/desktop/electron-builder.yml
index c9580af30..4ec435038 100644
--- a/packages/desktop/electron-builder.yml
+++ b/packages/desktop/electron-builder.yml
@@ -11,12 +11,15 @@ copyright: Copyright © 2026 Inkeep
# electron-rebuild / native-module ABI compilation cannot drift.
electronVersion: "41.2.1"
-# Gate @electron/rebuild per platform: mac/win rebuild native deps (mac needs
-# node-pty's ABI; win cross-builds per-arch binaries), Linux skips it (all shipped
-# Linux natives are N-API prebuilds; the only node-gyp deps are unused, unbuilt-by-
-# design transitive server deps that fail to compile against Electron's v8 headers
-# under GCC -Werror). See scripts/before-build.mjs for the full rationale.
-beforeBuild: scripts/before-build.mjs
+# @electron/rebuild runs for mac and Windows from this config: mac needs
+# node-pty's ABI rebuilt, Windows cross-builds its per-arch binaries.
+#
+# Linux skips the pass instead, via the `electron-builder.linux.yml` overlay
+# (`npmRebuild: false`) — Linux builds MUST pass `--config
+# electron-builder.linux.yml`. The skip is NOT expressed as a `beforeBuild` hook
+# returning false: in app-builder-lib that also asserts "node_modules are staged
+# externally", which suppresses dependency collection entirely and ships an asar
+# the app cannot start from. That overlay documents the mechanism in full.
directories:
output: dist-desktop
@@ -472,7 +475,7 @@ linux:
# The arm64 deb is built on a NATIVE arm64 runner (the `build-linux` matrix
# in .github/workflows/desktop-build-win-linux.yml), never cross-compiled:
# pnpm installs only the host-arch `@parcel/watcher` prebuild and the Linux
- # build skips @electron/rebuild by design (`beforeBuild` above), so an
+ # build skips @electron/rebuild by design (see the overlay config), so an
# x64-host arm64 deb would package but ship the wrong native binaries.
target:
- target: AppImage
diff --git a/packages/desktop/package.json b/packages/desktop/package.json
index a51605dc9..fbb649059 100644
--- a/packages/desktop/package.json
+++ b/packages/desktop/package.json
@@ -22,7 +22,7 @@
"build:mac": "pnpm run build:desktop && node scripts/prepare-universal.mjs && node scripts/stage-parcel-watcher.mjs && electron-builder --mac --publish never",
"build:mac:unsigned": "pnpm run build:desktop && node scripts/prepare-universal.mjs && node scripts/stage-parcel-watcher.mjs && CSC_IDENTITY_AUTO_DISCOVERY=false electron-builder --mac --publish never -c.mac.identity=null",
"build:win": "pnpm run build:desktop && node scripts/prepare-platform-natives.mjs && node scripts/stage-parcel-watcher.mjs && electron-builder --win --publish never",
- "build:linux": "pnpm run build:desktop && node scripts/prepare-platform-natives.mjs && node scripts/stage-parcel-watcher.mjs && electron-builder --linux --publish never",
+ "build:linux": "pnpm run build:desktop && node scripts/prepare-platform-natives.mjs && node scripts/stage-parcel-watcher.mjs && electron-builder --linux --publish never --config electron-builder.linux.yml",
"prepare:universal": "node scripts/prepare-universal.mjs",
"prepare:platform-natives": "node scripts/prepare-platform-natives.mjs",
"postinstall": "node scripts/postinstall.mjs",
diff --git a/packages/desktop/scripts/assert-asar-complete.mjs b/packages/desktop/scripts/assert-asar-complete.mjs
new file mode 100644
index 000000000..c0523f7f7
--- /dev/null
+++ b/packages/desktop/scripts/assert-asar-complete.mjs
@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * Effect-level control: the packaged `app.asar` must actually carry the runtime
+ * dependencies the main process imports.
+ *
+ * A packaged Electron app whose asar has no `node_modules` installs fine and
+ * then dies on the first bare import, BEFORE `app.ready` — so there is no
+ * window, no dialog, and no crash report. From the outside it is
+ * indistinguishable from "nothing happened". Every other packaging control we
+ * have (an executable exists, the smoke suite passes) stays green through it,
+ * because the smoke suite drives the electron-vite `out/` build where the dev
+ * `node_modules` are still on disk to resolve against.
+ *
+ * Reads the asar header directly rather than shelling out to the `asar` CLI:
+ * the format is a 16-byte prefix whose last uint32 is the length of a JSON
+ * directory listing, which is all we need and costs one read of the first few
+ * hundred KB of a ~250 MB file.
+ *
+ * Usage: node assert-asar-complete.mjs <search-root> [label]
+ * <search-root> directory to find app.asar under (e.g. dist-desktop)
+ */
+
+import { closeSync, existsSync, openSync, readdirSync, readSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Packages asserted present by name. `pino` is the one that actually broke —
+ * `desktop-logger` imports it at module scope, so it is the first bare specifier
+ * the main process resolves and thus the observed failure. The others are listed
+ * so a partial collection (rather than a wholesale omission) still fails.
+ */
+const REQUIRED_PACKAGES = ['pino', 'electron-updater'];
+
+/**
+ * EVERY asar under the root, not the first one found. A single `electron-builder
+ * --win` run with `arch: [x64, arm64]` writes `win-unpacked/` AND
+ * `win-arm64-unpacked/`, each with its own `app.asar`; checking only one would
+ * let a broken second arch ship. (`--dir` builds the host arch alone, which is
+ * why the PR-gate cells see exactly one.)
+ */
+function findAsars(root) {
+ if (!existsSync(root)) return [];
+ const found = [];
+ const stack = [root];
+ while (stack.length > 0) {
+ const dir = stack.pop();
+ let entries;
+ try {
+ entries = readdirSync(dir, { withFileTypes: true });
+ } catch {
+ continue;
+ }
+ for (const entry of entries) {
+ const full = join(dir, entry.name);
+ if (entry.isFile() && entry.name === 'app.asar') found.push(full);
+ // `*-unpacked/` trees mirror the asar's contents and would double the walk.
+ if (entry.isDirectory() && !entry.name.endsWith('.asar.unpacked')) stack.push(full);
+ }
+ }
+ return found.sort();
+}
+
+/** Guards against a truncated or corrupt asar producing a bare stack trace. */
+const MAX_HEADER_BYTES = 64 * 1024 * 1024;
+
+function readAsarHeader(asarPath) {
+ const fd = openSync(asarPath, 'r');
+ try {
+ const prefix = Buffer.alloc(16);
+ if (readSync(fd, prefix, 0, 16, 0) < 16) {
+ throw new Error('file is shorter than the 16-byte asar header prefix');
+ }
+ const jsonSize = prefix.readUInt32LE(12);
+ if (jsonSize === 0 || jsonSize > MAX_HEADER_BYTES) {
+ throw new Error(
+ `implausible asar header length (${jsonSize} bytes) — file is not a valid asar`,
+ );
+ }
+ const json = Buffer.alloc(jsonSize);
+ if (readSync(fd, json, 0, jsonSize, 16) < jsonSize) {
+ throw new Error(`asar header truncated (wanted ${jsonSize} bytes)`);
+ }
+ return JSON.parse(json.toString('utf8'));
+ } finally {
+ closeSync(fd);
+ }
+}
+
+const searchRoot = process.argv[2];
+const label = process.argv[3] ?? searchRoot;
+
+if (!searchRoot) {
+ console.error('usage: assert-asar-complete.mjs <search-root> [label]');
+ process.exit(2);
+}
+
+const asarPaths = findAsars(searchRoot);
+if (asarPaths.length === 0) {
+ console.error(`::error::${label}: no app.asar found under ${searchRoot}`);
+ process.exit(1);
+}
+
+let failed = false;
+
+for (const asarPath of asarPaths) {
+ const sizeMb = (statSync(asarPath).size / 1024 / 1024).toFixed(1);
+
+ let header;
+ try {
+ header = readAsarHeader(asarPath);
+ } catch (error) {
+ console.error(
+ `::error::${label}: could not read the asar header of ${asarPath} (${sizeMb} MB): ${error.message}`,
+ );
+ failed = true;
+ continue;
+ }
+
+ const top = header.files ?? {};
+ const nodeModules = top.node_modules;
+ if (nodeModules == null) {
+ console.error(
+ `::error::${label}: app.asar contains NO node_modules directory — the packaged app ` +
+ `cannot start (bare imports fail before app.ready, with no window and no dialog). ` +
+ `asar: ${asarPath} (${sizeMb} MB), top-level entries: ${Object.keys(top).sort().join(', ')}`,
+ );
+ failed = true;
+ continue;
+ }
+
+ const packages = Object.keys(nodeModules.files ?? {});
+ const missing = REQUIRED_PACKAGES.filter((name) => !packages.includes(name));
+ if (missing.length > 0) {
+ console.error(
+ `::error::${label}: app.asar node_modules is missing required package(s): ` +
+ `${missing.join(', ')}. Present: ${packages.length} package(s). asar: ${asarPath}`,
+ );
+ failed = true;
+ continue;
+ }
+
+ console.log(
+ `asar completeness OK (${label}): ${asarPath} (${sizeMb} MB), ` +
+ `node_modules with ${packages.length} package(s), required present: ${REQUIRED_PACKAGES.join(', ')}`,
+ );
+}
+
+if (failed) process.exit(1);
+
+console.log(`asar completeness: ${asarPaths.length} asar(s) checked under ${searchRoot}`);
diff --git a/packages/desktop/scripts/before-build.mjs b/packages/desktop/scripts/before-build.mjs
deleted file mode 100644
index ddc25ab89..000000000
--- a/packages/desktop/scripts/before-build.mjs
+++ /dev/null
@@ -1,28 +0,0 @@
-/**
- * electron-builder `beforeBuild` hook.
- *
- * Return value contract (app-builder-lib Packager.installAppDependencies):
- * `false` skips the @electron/rebuild native-dependency pass; any other value
- * lets it run. We gate it on the build host platform (each platform packages on
- * its own native runner, so host === target here).
- *
- * macOS + Windows → run the rebuild. macOS ships node-pty (a node-gyp/nan addon,
- * NOT N-API) which must be rebuilt for Electron's ABI; Windows cross-builds the
- * per-arch native binaries (its arm64 installer needs them) and compiles cleanly
- * under MSVC.
- *
- * Linux → skip it. Every native module that actually ships in the Linux package
- * is N-API and loads in Electron straight from its prebuilt `.node` with no
- * rebuild: @napi-rs/keyring, @inkeep/open-knowledge-native-config, and
- * @parcel/watcher. node-pty is excluded from the Linux `files`. The only reason
- * @electron/rebuild has anything to compile is unused node-gyp transitive deps
- * dragged in through the bundled server (node-liblzma via just-bash,
- * @mongodb-js/zstd) — pnpm ignores their build scripts, so they are unbuilt in
- * every normal install and the app already runs without them. Compiling them
- * adds nothing and hard-fails on Linux GCC: node-liblzma's binding.gyp forces
- * `-Werror`, and Electron's bundled v8 headers trip `-Wcomment` (ASCII-art
- * comments ending in `\`). Skipping the pass keeps the Linux draft build green.
- */
-export default async function beforeBuild() {
- return process.platform !== 'linux';
-}