Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Cut dead weight from the desktop app bundle (PRD-9159) (#5991)

Andrew Mikofalvye48c8a05a16a
diff --git a/.changeset/smaller-desktop-download.md b/.changeset/smaller-desktop-download.md
new file mode 100644
index 000000000..a2fe82a89
--- /dev/null
+++ b/.changeset/smaller-desktop-download.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge-desktop": patch
+---
+
+The desktop app download is smaller on every platform; the macOS disk image drops from about 347 MB to about 189 MB.
diff --git a/knip.config.ts b/knip.config.ts
index 69344114d..0004a763a 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -149,11 +149,15 @@ export default {
'packages/server': {
entry: ['src/**/*.test.ts', 'src/parse-worker.ts'],
project: 'src/**',
- ignoreDependencies: ['@types/shell-quote'],
+ ignoreDependencies: [
+ '@types/shell-quote',
+ ],
},
'packages/cli': {
entry: ['src/**/*.test.ts', 'scripts/*.ts', 'tests/**/*.ts', 'src/parse-worker.ts'],
- ignoreDependencies: ['yjs'],
+ ignoreDependencies: [
+ 'yjs',
+ ],
},
'packages/desktop': {
entry: [
diff --git a/packages/app/tests/integration/bug3-source-mode-writeback.test.ts b/packages/app/tests/integration/bug3-source-mode-writeback.test.ts
index a50b00123..4549c74b3 100644
--- a/packages/app/tests/integration/bug3-source-mode-writeback.test.ts
+++ b/packages/app/tests/integration/bug3-source-mode-writeback.test.ts
@@ -1,3 +1,4 @@
+
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
diff --git a/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts b/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts
index 6fcdc23f2..4fc2c11f9 100644
--- a/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts
+++ b/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts
@@ -1,3 +1,4 @@
+
import { setTimeout as wait } from 'node:timers/promises';
import { normalizeBridge } from '@inkeep/open-knowledge-core';
import { updateYFragment } from '@tiptap/y-tiptap';
diff --git a/packages/app/tests/integration/interior-edit-freshness.test.ts b/packages/app/tests/integration/interior-edit-freshness.test.ts
index 40b5cdfd6..9f2f6feb6 100644
--- a/packages/app/tests/integration/interior-edit-freshness.test.ts
+++ b/packages/app/tests/integration/interior-edit-freshness.test.ts
@@ -1,3 +1,4 @@
+
import { setTimeout as wait } from 'node:timers/promises';
import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
diff --git a/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts b/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts
index 93666af70..2a085742b 100644
--- a/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts
+++ b/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts
@@ -1,3 +1,4 @@
+
import { setTimeout as wait } from 'node:timers/promises';
import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
diff --git a/packages/app/tests/integration/producer-guard-wiring.test.ts b/packages/app/tests/integration/producer-guard-wiring.test.ts
index 867598d34..878d5196b 100644
--- a/packages/app/tests/integration/producer-guard-wiring.test.ts
+++ b/packages/app/tests/integration/producer-guard-wiring.test.ts
@@ -1,3 +1,4 @@
+
import { setTimeout as wait } from 'node:timers/promises';
import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
diff --git a/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts b/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts
index 0970ac12f..4ada3cf26 100644
--- a/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts
+++ b/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts
@@ -1,3 +1,4 @@
+
import { randomUUID } from 'node:crypto';
import { afterEach, describe, expect, test } from 'vitest';
import { agentWriteMd, createTestServer, type TestServer } from './test-harness';
diff --git a/packages/app/tests/integration/qa-045-restore-after-gc.test.ts b/packages/app/tests/integration/qa-045-restore-after-gc.test.ts
index b632185e1..cbe2b705f 100644
--- a/packages/app/tests/integration/qa-045-restore-after-gc.test.ts
+++ b/packages/app/tests/integration/qa-045-restore-after-gc.test.ts
@@ -1,3 +1,4 @@
+
import { execFileSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { join } from 'node:path';
diff --git a/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts b/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts
index c530ce4ba..89bc9b4d9 100644
--- a/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts
+++ b/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts
@@ -1,3 +1,4 @@
+
import { randomUUID } from 'node:crypto';
import { afterAll, afterEach, beforeAll, describe, expect, test } from 'vitest';
import type * as Y from 'yjs';
diff --git a/packages/app/tests/integration/undo-after-rollback.test.ts b/packages/app/tests/integration/undo-after-rollback.test.ts
index d3767adc9..a78aeb0e4 100644
--- a/packages/app/tests/integration/undo-after-rollback.test.ts
+++ b/packages/app/tests/integration/undo-after-rollback.test.ts
@@ -1,3 +1,4 @@
+
import { ROLLBACK_ORIGIN } from '@inkeep/open-knowledge-server';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
import * as Y from 'yjs';
diff --git a/packages/app/tests/integration/undo-recycle-reset.test.ts b/packages/app/tests/integration/undo-recycle-reset.test.ts
index b076f955c..e7cc69c3f 100644
--- a/packages/app/tests/integration/undo-recycle-reset.test.ts
+++ b/packages/app/tests/integration/undo-recycle-reset.test.ts
@@ -1,3 +1,4 @@
+
import { writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
diff --git a/packages/app/tests/integration/undo-rederive-survival.test.ts b/packages/app/tests/integration/undo-rederive-survival.test.ts
index 7935e35f8..9ddcd0730 100644
--- a/packages/app/tests/integration/undo-rederive-survival.test.ts
+++ b/packages/app/tests/integration/undo-rederive-survival.test.ts
@@ -1,3 +1,4 @@
+
import { prependFrontmatter } from '@inkeep/open-knowledge-core';
import { Plugin, PluginKey } from '@tiptap/pm/state';
import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
diff --git a/packages/cli/src/commands/start.test.ts b/packages/cli/src/commands/start.test.ts
index 53ec2ceeb..abedd90e7 100644
--- a/packages/cli/src/commands/start.test.ts
+++ b/packages/cli/src/commands/start.test.ts
@@ -1546,6 +1546,23 @@ describe('resolveBundledReactShellDir (candidate-path probe)', () => {
test('returns undefined when no candidate exists (→ API/MCP-only degrade)', () => {
expect(resolveBundledReactShellDir(() => false)).toBeUndefined();
});
+
+ test('inside a packaged desktop app, serves the app window bundle beside app.asar', () => {
+ const present = new Set([
+ '/OK.app/Contents/Resources/app.asar',
+ '/OK.app/Contents/Resources/app',
+ ]);
+ expect(
+ resolveBundledReactShellDir((p) => present.has(p), '/OK.app/Contents/Resources/cli/dist'),
+ ).toBe('/OK.app/Contents/Resources/app');
+ });
+
+ test('outside a packaged desktop app, never serves a sibling app source dir', () => {
+ const present = new Set(['/repo/packages/app']);
+ expect(
+ resolveBundledReactShellDir((p) => present.has(p), '/repo/packages/cli/dist'),
+ ).toBeUndefined();
+ });
});
describe('resolveStartShellDir (the Wave 3 default-flip decision)', () => {
diff --git a/packages/cli/src/commands/start.ts b/packages/cli/src/commands/start.ts
index d64b17d85..88f0b89ed 100644
--- a/packages/cli/src/commands/start.ts
+++ b/packages/cli/src/commands/start.ts
@@ -66,13 +66,17 @@ export function parseOnlyModule(value: string): OnlyModule {
export function resolveBundledReactShellDir(
existsFn: (path: string) => boolean = fsExistsSync,
+ cliDir: string = import.meta.dirname ?? new URL('.', import.meta.url).pathname,
): string | undefined {
- const cliDir = import.meta.dirname ?? new URL('.', import.meta.url).pathname;
- return [
+ const candidates = [
pathResolve(cliDir, 'public'),
pathResolve(cliDir, '../../app/dist'),
pathResolve(cliDir, '../../../app/dist'),
- ].find((p) => existsFn(p));
+ ];
+ if (existsFn(pathResolve(cliDir, '../../app.asar'))) {
+ candidates.push(pathResolve(cliDir, '../../app'));
+ }
+ return candidates.find((p) => existsFn(p));
}
export function resolveStartShellDir(input: {
diff --git a/packages/cli/tsdown.config.ts b/packages/cli/tsdown.config.ts
index 44a2242ac..3bbc9f679 100644
--- a/packages/cli/tsdown.config.ts
+++ b/packages/cli/tsdown.config.ts
@@ -11,8 +11,7 @@ import { defineConfig } from 'tsdown';
const jsoncParserEsmEntry = createRequire(import.meta.url).resolve('jsonc-parser/lib/esm/main.js');
// Native addons stay external in EVERY build — they ship .node binaries
-// resolved at runtime and the desktop bundle places them under
-// app.asar.unpacked/node_modules/.
+// resolved at runtime.
const nativeAddonNeverBundle = [
'@parcel/watcher',
'@napi-rs/keyring',
diff --git a/packages/core/src/bridge/compose.ts b/packages/core/src/bridge/compose.ts
index f4cc8a286..2a597ec3d 100644
--- a/packages/core/src/bridge/compose.ts
+++ b/packages/core/src/bridge/compose.ts
@@ -1,3 +1,4 @@
+
import { prependFrontmatter, stripFrontmatter } from '../extensions/frontmatter.ts';
export type ComposeAdjustment = 'none' | 'body' | 'frontmatter' | 'unresolved';
diff --git a/packages/core/src/bridge/doc-boundary-space.ts b/packages/core/src/bridge/doc-boundary-space.ts
index e7e63f43d..ffd8fce06 100644
--- a/packages/core/src/bridge/doc-boundary-space.ts
+++ b/packages/core/src/bridge/doc-boundary-space.ts
@@ -1,3 +1,4 @@
+
import { FRONTMATTER_RE, stripFrontmatter } from '../extensions/frontmatter.ts';
import { carriedEdgeEmpties, type DocEdgeEmpties } from '../markdown/doc-edge-blank-runs.ts';
diff --git a/packages/core/src/markdown/comment-promoter.ts b/packages/core/src/markdown/comment-promoter.ts
index fc267cbea..fb0ba5a7c 100644
--- a/packages/core/src/markdown/comment-promoter.ts
+++ b/packages/core/src/markdown/comment-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Paragraph, PhrasingContent, Root, RootContent, Text } from 'mdast';
import { SKIP, visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/merged-walker.ts b/packages/core/src/markdown/merged-walker.ts
index bfd7e3109..fa3cfcd86 100644
--- a/packages/core/src/markdown/merged-walker.ts
+++ b/packages/core/src/markdown/merged-walker.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parent, Root } from 'mdast';
import { SKIP, visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/safe-url.ts b/packages/core/src/markdown/safe-url.ts
index 4d3250d3a..8be632ba4 100644
--- a/packages/core/src/markdown/safe-url.ts
+++ b/packages/core/src/markdown/safe-url.ts
@@ -1,3 +1,4 @@
+
export const SAFE_URL_SCHEMES = ['https', 'http', 'mailto', 'tel', 'ftp', 'sms'] as const;
const SCHEME_ALT = SAFE_URL_SCHEMES.map((s) => `${s}:`).join('|');
diff --git a/packages/desktop/electron-builder.yml b/packages/desktop/electron-builder.yml
index 073c66eea..82415ad3f 100644
--- a/packages/desktop/electron-builder.yml
+++ b/packages/desktop/electron-builder.yml
@@ -29,9 +29,32 @@ directories:
# Core-assert: the CLI's build:assets step produces packages/cli/dist/public/
# (Vite build of packages/app/, copied by `cp -r ../app/dist dist/public`).
# We consume that output directly — no separate renderer build for the app.
+#
+# STOP: win.files and linux.files replace this list for files outside
+# node_modules, so each repeats the three anchored patterns.
files:
- - "out/**/*"
- - "!**/*.map"
+ - &app-out "out/**/*"
+ - &no-renderer "!out/renderer/**"
+ - &no-maps "!**/*.map"
+ - "!**/node_modules/@inkeep/*/src/**"
+ - "!**/node_modules/**/*.{ts,mts,cts,tsx}"
+ - "!**/node_modules/@inkeep/open-knowledge/dist/public/**"
+ - "!**/node_modules/@inkeep/open-knowledge-native-config/**"
+ - "!**/node_modules/mermaid/dist/mermaid{.js,.min.js,.esm.mjs,.esm.min.mjs}"
+ - "!**/node_modules/mermaid/dist/chunks/mermaid.esm{,.min}/**"
+ - "!**/node_modules/@mermaid-js/parser/dist/mermaid-parser.esm{,.min}.mjs"
+ - "!**/node_modules/@mermaid-js/parser/dist/chunks/mermaid-parser.esm{,.min}/**"
+ - "!**/node_modules/cytoscape-fcose/demo/**"
+ - "!**/node_modules/sql.js/dist/*-debug*"
+ - "!**/node_modules/sql.js/dist/*-asm*"
+ - "!**/node_modules/sql.js/dist/*-browser*"
+ - "!**/node_modules/sql.js/dist/worker.*"
+ - "!**/node_modules/just-bash/vendor/cpython-emscripten/**"
+ - "!**/node_modules/just-bash/dist/bin/**"
+ - "!**/node_modules/just-bash/dist/bundle/browser.js"
+ - "!**/node_modules/quickjs-emscripten/**"
+ - "!**/node_modules/quickjs-emscripten-core/**"
+ - "!**/node_modules/@jitl/**"
extraResources:
- from: "../cli/dist/public"
@@ -49,23 +72,18 @@ extraResources:
to: "locales"
filter: ["**/messages.json"]
# M6a: ship the CLI bundle + wrapper so the packaged .app can host
- # `ok` on PATH via ELECTRON_RUN_AS_NODE=1. Filter keeps cli/dist/public/**
- # intact — `ok ui` from the wrapper reads it via $APP_PATH/Contents/
- # Resources/cli/dist/public/ (distinct consumer from the React bundle
- # copy above that the BrowserWindow loads from Contents/Resources/app/).
- # Two copies, deliberately — see SPEC §5 AC1.11 and OQ-22.
+ # `ok` on PATH via ELECTRON_RUN_AS_NODE=1.
# Ships the whole bundled CLI, INCLUDING `cli/dist/native/` — the prebuilt
# native-config loader + `.node` the CLI build copies there (Option 3: bundle
# the addon into the CLI; reports/native-addon-npm-distribution/REPORT.md). The
- # spawned `ok` subprocess resolves the addon dist-relative from there, so this
- # one rule covers the bundled-CLI consumer; the per-package `cli/node_modules`
- # copy + asarUnpack below stay for the desktop MAIN process's in-process load.
+ # spawned `ok` subprocess resolves the addon dist-relative from there.
# The filter must not exclude `.node`/`.js`/`package.json` — guarded by
# tests/unit/electron-builder-cli-native-deps.test.ts.
- from: "../cli/dist"
to: "cli/dist"
filter:
- "**/*"
+ - "!public/**"
- "!**/*.map"
# Post-review Minor #21: tsdown emits `.d.mts` + `.d.mts.map` for
# every source module. TypeScript declarations have no runtime
@@ -180,12 +198,6 @@ asarUnpack:
- "**/detect-libc/**"
- "**/@napi-rs/keyring/**"
- "**/@napi-rs/keyring-*/**"
- # The desktop main process loads the addon in-process (the MCP repair sweep's
- # Codex TOML write). Keep its napi loader and the `.node` it requires
- # relatively co-located on the real filesystem — a loader left inside
- # app.asar resolving `require('./native-config.<platform>.node')` against an
- # unpacked sibling is the fragile path; unpack the whole package dir instead.
- - "**/@inkeep/open-knowledge-native-config/**"
- "**/simple-git/**"
# node-pty ships its native pty.node addon AND an extensionless `spawn-helper`
# binary under prebuilds/<platform>-<arch>/. The `**/*.node` rule above unpacks
@@ -402,7 +414,7 @@ win:
# never published (internal QA only).
#
# node-pty ships in the Windows package: the terminal runs on ConPTY via the
- # win32 prebuilds. `files` merges with the top-level list. The prune mirrors
+ # win32 prebuilds. The prune mirrors
# the Linux block (no foreign-platform prebuilds, no ~10 MB/arch .pdb debug
# symbols), and BOTH win32 arch prebuilds stay in BOTH per-arch installers —
# the addon picks prebuilds/win32-<process.arch> at runtime, which keeps
@@ -414,18 +426,15 @@ win:
# ship builder-host binaries. Pruning build/** makes the per-arch prebuild
# the only loadable addon. third_party/ is ConPTY C++ source weight with no
# runtime role.
- #
- # native-config's cargo `target/` tree is darwin build intermediates that
- # the blanket asarUnpack rule would otherwise drag in. Beyond dead weight,
- # its `.fingerprint` paths nest past MAX_PATH under the install dir and
- # the x86 NSIS uninstaller cannot delete them (VM-verified residue).
files:
+ - *app-out
+ - *no-renderer
+ - *no-maps
- "!**/node_modules/node-pty/prebuilds/**/*.pdb"
- "!**/node_modules/node-pty/prebuilds/darwin-*/**"
- "!**/node_modules/node-pty/prebuilds/linux-*/**"
- "!**/node_modules/node-pty/build/**"
- "!**/node_modules/node-pty/third_party/**"
- - "!**/node_modules/@inkeep/open-knowledge-native-config/target/**"
# conpty.dll + OpenConsole.exe (under prebuilds/win32-*/conpty/) ship with
# Microsoft's Authenticode signatures and must keep them — re-signing would
# replace Microsoft's signature with ours and split the pair's provenance.
@@ -542,13 +551,14 @@ linux:
# node-pty publishes every platform prebuild in one package. Drop
# foreign-platform binaries and Windows debug symbols, but keep both Linux
# prebuilds so each installer carries the correct ELF regardless of builder
- # architecture. native-config's darwin cargo `target/` tree stays excluded
- # (see win.files for the rationale).
+ # architecture.
files:
+ - *app-out
+ - *no-renderer
+ - *no-maps
- "!**/node_modules/node-pty/prebuilds/**/*.pdb"
- "!**/node_modules/node-pty/prebuilds/darwin-*/**"
- "!**/node_modules/node-pty/prebuilds/win32-*/**"
- - "!**/node_modules/@inkeep/open-knowledge-native-config/target/**"
extraResources:
# Linux-layout wrapper ships under the same canonical destination as
# the mac one so path-install + the deb postinst agree on one path.
diff --git a/packages/desktop/scripts/afterPack.mjs b/packages/desktop/scripts/afterPack.mjs
index 40ec251e5..26d226041 100644
--- a/packages/desktop/scripts/afterPack.mjs
+++ b/packages/desktop/scripts/afterPack.mjs
@@ -3,6 +3,7 @@ import { execFileSync } from 'node:child_process';
import { chmodSync, copyFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { FuseV1Options, FuseVersion, flipFuses } from '@electron/fuses';
+import { assertPackagedBundle } from './assert-packaged-bundle.mjs';
import { ensureNodePtySpawnHelperExecutable } from './ensure-node-pty-exec.mjs';
import { createFuseFailure } from './packaging-diagnostics.mjs';
import { resolveElectronBinary } from './resolve-electron-binary.mjs';
@@ -80,6 +81,12 @@ export default async function afterPack(context) {
);
}
+ assertPackagedBundle(
+ electronPlatformName === 'darwin'
+ ? join(appOutDir, `${appName}.app`, 'Contents', 'Resources')
+ : join(appOutDir, 'resources'),
+ );
+
if (electronPlatformName !== 'darwin') {
await flipElectronFuses(electronBinary, electronPlatformName);
console.log(
diff --git a/packages/desktop/scripts/assert-packaged-bundle.mjs b/packages/desktop/scripts/assert-packaged-bundle.mjs
new file mode 100644
index 000000000..3dd37c4e5
--- /dev/null
+++ b/packages/desktop/scripts/assert-packaged-bundle.mjs
@@ -0,0 +1,102 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { listAsarHeaderPaths, readAsarHeader } from './lib/asar-header.mjs';
+
+export const FORBIDDEN_BUNDLE_PATHS = [
+ {
+ pattern: /(^|\/)CACHEDIR\.TAG$/,
+ reason: 'a build cache directory (a Rust cargo `target/` tree)',
+ },
+ {
+ pattern: /^app\.asar\/(?!(out|node_modules)(\/|$)|package\.json$)/,
+ reason: 'desktop package files outside out/, node_modules/ and package.json',
+ },
+ {
+ pattern: /^app\.asar\/out\/renderer\//,
+ reason: "electron-vite's renderer build, which only unpackaged runs load",
+ },
+ {
+ pattern:
+ /^(cli\/dist|app\.asar(\.unpacked)?\/node_modules\/@inkeep\/open-knowledge\/dist)\/public\//,
+ reason: 'a second copy of the web app; Resources/app is the only one',
+ },
+ {
+ pattern: /^app\.asar(\.unpacked)?\/node_modules\/@inkeep\/open-knowledge-native-config\//,
+ reason: 'a native-config package in the asar; the CLI loads its own dist/native copy',
+ },
+ {
+ pattern: /^app\.asar(\.unpacked)?\/node_modules\/@inkeep\/[^/]+\/src\//,
+ reason: 'workspace TypeScript sources, which no packaged process loads',
+ },
+];
+
+export const REQUIRED_BUNDLE_PATHS = [
+ {
+ pattern: /^app\.asar\/package\.json$/,
+ reason: 'app.asar with its package.json',
+ },
+ {
+ pattern:
+ /^app\.asar\.unpacked\/node_modules\/@inkeep\/open-knowledge\/dist\/native\/index\.js$/,
+ reason: "the main process's native-config loader, unpacked",
+ },
+ {
+ pattern:
+ /^app\.asar\.unpacked\/node_modules\/@inkeep\/open-knowledge\/dist\/native\/[^/]+\.node$/,
+ reason: "the main process's native-config addon, unpacked",
+ },
+ {
+ pattern: /^cli\/dist\/native\/index\.js$/,
+ reason: "the bundled CLI's native-config loader",
+ },
+ {
+ pattern: /^cli\/dist\/native\/[^/]+\.node$/,
+ reason: "the bundled CLI's native-config addon",
+ },
+];
+
+export function findForbiddenBundlePaths(paths) {
+ return FORBIDDEN_BUNDLE_PATHS.flatMap(({ pattern, reason }) => {
+ const hits = paths.filter((p) => pattern.test(p));
+ return hits.length === 0 ? [] : [{ reason, count: hits.length, example: hits[0] }];
+ });
+}
+
+export function findMissingBundlePaths(paths) {
+ return REQUIRED_BUNDLE_PATHS.filter(({ pattern }) => !paths.some((p) => pattern.test(p))).map(
+ ({ reason }) => reason,
+ );
+}
+
+function walk(dir, root, out) {
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const abs = join(dir, entry.name);
+ if (entry.isDirectory()) walk(abs, root, out);
+ else out.push(relative(root, abs).split(sep).join('/'));
+ }
+ return out;
+}
+
+export function listBundlePaths(resourcesDir) {
+ const asarPath = join(resourcesDir, 'app.asar');
+ const onDisk = walk(resourcesDir, resourcesDir, []).filter((p) => p !== 'app.asar');
+ const inAsar = existsSync(asarPath)
+ ? listAsarHeaderPaths(readAsarHeader(asarPath)).map((p) => `app.asar/${p}`)
+ : [];
+ return [...onDisk, ...inAsar];
+}
+
+export function assertPackagedBundle(resourcesDir) {
+ const paths = listBundlePaths(resourcesDir);
+ const problems = [
+ ...findForbiddenBundlePaths(paths).map(
+ (v) => ` - carries ${v.reason}: ${v.count} path(s), e.g. Resources/${v.example}`,
+ ),
+ ...findMissingBundlePaths(paths).map((reason) => ` - lacks ${reason}`),
+ ];
+ if (problems.length === 0) return;
+ throw new Error(
+ `[afterPack] the packaged app's Resources/ is not laid out the way its processes load it:\n${problems.join('\n')}\n` +
+ 'Fix the `files` / `extraResources` / `asarUnpack` rules in electron-builder.yml.',
+ );
+}
diff --git a/packages/desktop/scripts/lib/asar-header.mjs b/packages/desktop/scripts/lib/asar-header.mjs
index 46665a41d..d86589765 100644
--- a/packages/desktop/scripts/lib/asar-header.mjs
+++ b/packages/desktop/scripts/lib/asar-header.mjs
@@ -24,3 +24,16 @@ export function readAsarHeader(asarPath) {
closeSync(fd);
}
}
+
+export function listAsarHeaderPaths(header) {
+ const paths = [];
+ const visit = (node, prefix) => {
+ for (const [name, entry] of Object.entries(node.files ?? {})) {
+ const path = prefix === '' ? name : `${prefix}/${name}`;
+ paths.push(path);
+ if (typeof entry === 'object' && entry !== null && 'files' in entry) visit(entry, path);
+ }
+ };
+ visit(header, '');
+ return paths.sort();
+}
diff --git a/packages/desktop/tests/smoke/native-config-e2e.md b/packages/desktop/tests/smoke/native-config-e2e.md
index 8b978137c..44e0c59f0 100644
--- a/packages/desktop/tests/smoke/native-config-e2e.md
+++ b/packages/desktop/tests/smoke/native-config-e2e.md
@@ -9,9 +9,9 @@
| Bundle is produced + loadable + round-trips (parse / upsert / symlink) from `packages/cli/dist/native/` | Real (runs in `pnpm check`) | `packages/desktop/tests/unit/verify-native-config-driver.test.mjs` (end-to-end test) |
| Driver maps `.dmg`/`.app`/dir inputs + exit codes | Real (unit) | same test file |
| Loads from a packaged `.app`/`.dmg` shipped layout | Real, but needs a built artifact | this runbook, Step 2 (`verify-native-config-in-packaged-dmg.mjs`) |
-| Loads **in the Electron main process** (hardened runtime + asar) | Deferred to signed-DMG QA | this runbook, Step 3 |
+| Loads **in the Electron main process** (hardened runtime + asar) | Quick check on any built `.app`; Codex round-trip deferred to signed-DMG QA | this runbook, Step 3 |
-The addon is pure computation over a napi N-API surface that is ABI-stable across Node and Electron, so the Node-load checks (Steps 1–2) are a faithful proof of the bundle + layout + loadability. Step 3 (the in-Electron-process confirmation) is the only part that genuinely needs a packaged runtime, and it is gated on a built DMG.
+The addon is pure computation over a napi N-API surface that is ABI-stable across Node and Electron, so the Node-load checks (Steps 1–2) are a faithful proof of the bundle + layout + loadability. Step 3 (the in-Electron-process confirmation) is the only part that genuinely needs a packaged runtime: its quick check runs on any built `.app`, and only its Codex round-trip waits for a signed DMG.
---
@@ -44,15 +44,23 @@ The driver mounts the DMG read-only, copies the first `.app`, detaches, and load
---
-## Step 3 — In-Electron-process confirmation (deferred — needs a built DMG)
+## Step 3 — In-Electron-process confirmation (quick check on any built `.app`; Codex round-trip deferred to signed-DMG QA)
The Node-load checks above do not exercise the Electron main process's own resolution path. To confirm the addon loads in-process inside the packaged app:
1. Launch the packaged app from `/Applications/`.
2. Open a project so the MCP repair sweep runs (it loads the addon in-process via `writeUserMcpConfigs -> getTomlConfigEngine`).
-3. Register OK into a Codex `~/.codex/config.toml` containing a comment + a 64-bit integer; confirm the comment + value survive (format-preserving write = the native engine ran). If the comment is stripped/reflowed, the desktop main fell back to the JS path — investigate `app.asar.unpacked/node_modules/@inkeep/open-knowledge-native-config` and the `dist/native` bundle.
+3. Register OK into a Codex `~/.codex/config.toml` containing a comment + a 64-bit integer; confirm the comment + value survive (format-preserving write = the native engine ran). If the comment is stripped/reflowed, the desktop main fell back to the JS path — investigate `app.asar.unpacked/node_modules/@inkeep/open-knowledge/dist/native/`, the main process's copy of the loader and `.node`. The native-config package itself is intentionally absent from the asar; the afterPack guard (`scripts/assert-packaged-bundle.mjs`) fails the build if it appears or if that loader or `.node` is missing.
-This step needs a built (ideally signed) DMG and a real Codex install, so it runs at release/QA time, not in the per-PR gate. The non-destructive fallback (D11) keeps a missing/failed addon safe — Codex registration simply degrades, never corrupts — so a Step-3 miss is a fidelity regression, not a data-loss one.
+A quicker in-Electron check needs only a built `.app`, no Codex install and no signing. Run the packaged binary as Node and load the main process's library copy. Any output other than `native` means the main process fell back to the JS engine:
+
+```bash
+R="/Applications/OpenKnowledge.app/Contents/Resources"
+ELECTRON_RUN_AS_NODE=1 "$R/../MacOS/OpenKnowledge" -e "import('$R/app.asar/node_modules/@inkeep/open-knowledge/dist/index.mjs').then((m) => console.log(m.getNativeTomlMcpEditor()?.backend))"
+# Expect: native
+```
+
+The Codex round-trip in item 3 needs a built (ideally signed) DMG and a real Codex install, so it runs at release/QA time, not in the per-PR gate. The non-destructive fallback (D11) keeps a missing/failed addon safe — Codex registration simply degrades, never corrupts — so a Step-3 miss is a fidelity regression, not a data-loss one.
---
diff --git a/packages/desktop/tests/support/synthetic-asar.test-helper.ts b/packages/desktop/tests/support/synthetic-asar.test-helper.ts
new file mode 100644
index 000000000..7eba92ee9
--- /dev/null
+++ b/packages/desktop/tests/support/synthetic-asar.test-helper.ts
@@ -0,0 +1,35 @@
+import { writeFileSync } from 'node:fs';
+
+interface AsarDir {
+ files: Record<string, AsarDir | { size: number; offset: string }>;
+}
+
+export function writeSyntheticAsar(path: string, header: object): void {
+ const json = Buffer.from(JSON.stringify(header), 'utf8');
+ const prefix = Buffer.alloc(16);
+ prefix.writeUInt32LE(4, 0);
+ prefix.writeUInt32LE(json.length + 8, 4);
+ prefix.writeUInt32LE(json.length + 4, 8);
+ prefix.writeUInt32LE(json.length, 12);
+ writeFileSync(path, Buffer.concat([prefix, json]));
+}
+
+export function writeHeaderOnlyAsar(path: string, files: readonly string[]): void {
+ const root: AsarDir = { files: {} };
+ for (const file of files) {
+ const segments = file.split('/');
+ let dir = root;
+ for (const segment of segments.slice(0, -1)) {
+ const next = dir.files[segment];
+ if (next && 'files' in next) {
+ dir = next;
+ } else {
+ const created: AsarDir = { files: {} };
+ dir.files[segment] = created;
+ dir = created;
+ }
+ }
+ dir.files[segments[segments.length - 1] as string] = { size: 0, offset: '0' };
+ }
+ writeSyntheticAsar(path, root);
+}
diff --git a/packages/desktop/tests/unit/after-pack-signing-order.test.mjs b/packages/desktop/tests/unit/after-pack-signing-order.test.mjs
index a6a6acdc8..0ffb84c56 100644
--- a/packages/desktop/tests/unit/after-pack-signing-order.test.mjs
+++ b/packages/desktop/tests/unit/after-pack-signing-order.test.mjs
@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { afterEach, describe, expect, test, vi } from 'vitest';
import afterPack, { assertAdHocSealCoversBundle } from '../../scripts/afterPack.mjs';
+import { writeHeaderOnlyAsar } from '../support/synthetic-asar.test-helper.ts';
import { removeTempDirBestEffort } from '../support/temp-dir-cleanup.test-helper.ts';
vi.mock('@electron/fuses', async (importOriginal) => ({
@@ -82,6 +83,17 @@ function packedApp() {
);
adHocMachO(spawnHelper);
chmodSync(spawnHelper, 0o644);
+ const resources = join(app, 'Contents/Resources');
+ for (const file of [
+ 'cli/dist/native/index.js',
+ 'cli/dist/native/native-config.darwin-arm64.node',
+ 'app.asar.unpacked/node_modules/@inkeep/open-knowledge/dist/native/index.js',
+ 'app.asar.unpacked/node_modules/@inkeep/open-knowledge/dist/native/native-config.darwin-arm64.node',
+ ]) {
+ mkdirSync(dirname(join(resources, file)), { recursive: true });
+ writeFileSync(join(resources, file), 'x');
+ }
+ writeHeaderOnlyAsar(join(resources, 'app.asar'), ['package.json']);
return { appOutDir, app, serverContents };
}
diff --git a/packages/desktop/tests/unit/assert-packaged-bundle.test.mjs b/packages/desktop/tests/unit/assert-packaged-bundle.test.mjs
new file mode 100644
index 000000000..25091aaf3
--- /dev/null
+++ b/packages/desktop/tests/unit/assert-packaged-bundle.test.mjs
@@ -0,0 +1,129 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { afterEach, describe, expect, test } from 'vitest';
+import {
+ assertPackagedBundle,
+ findForbiddenBundlePaths,
+ findMissingBundlePaths,
+} from '../../scripts/assert-packaged-bundle.mjs';
+import { writeHeaderOnlyAsar } from '../support/synthetic-asar.test-helper.ts';
+import { removeTempDirBestEffort } from '../support/temp-dir-cleanup.test-helper.ts';
+
+const tempDirs = [];
+
+afterEach(() => {
+ for (const dir of tempDirs.splice(0)) removeTempDirBestEffort(dir);
+});
+
+function writeTree(root, files) {
+ for (const file of files) {
+ mkdirSync(dirname(join(root, file)), { recursive: true });
+ writeFileSync(join(root, file), 'x');
+ }
+}
+
+function packResources({ asarFiles, diskFiles }) {
+ const dir = mkdtempSync(join(tmpdir(), 'ok-packaged-bundle-'));
+ tempDirs.push(dir);
+ const resources = join(dir, 'Resources');
+ mkdirSync(resources, { recursive: true });
+ if (asarFiles) writeHeaderOnlyAsar(join(resources, 'app.asar'), asarFiles);
+ writeTree(resources, diskFiles);
+ return resources;
+}
+
+const LIBRARY_NATIVE = 'app.asar.unpacked/node_modules/@inkeep/open-knowledge/dist/native';
+const SOUND_ASAR = [
+ 'package.json',
+ 'out/main/index.js',
+ 'node_modules/@inkeep/open-knowledge-server/dist/index.mjs',
+ 'node_modules/@inkeep/open-knowledge-core/dist/index.mjs',
+];
+const SOUND_DISK = [
+ 'app/index.html',
+ 'cli/dist/cli.mjs',
+ 'cli/dist/native/index.js',
+ 'cli/dist/native/native-config.linux-x64-gnu.node',
+ 'cli/node_modules/@inkeep/open-knowledge-native-config/index.js',
+ 'app.asar.unpacked/node_modules/@inkeep/open-knowledge/dist/index.mjs',
+ `${LIBRARY_NATIVE}/index.js`,
+ `${LIBRARY_NATIVE}/native-config.darwin-arm64.node`,
+ 'app.asar.unpacked/node_modules/@napi-rs/keyring/index.js',
+];
+const SOUND_PATHS = [...SOUND_DISK, ...SOUND_ASAR.map((p) => `app.asar/${p}`)];
+
+describe('findForbiddenBundlePaths', () => {
+ test('passes a sound bundle', () => {
+ expect(findForbiddenBundlePaths(SOUND_PATHS)).toEqual([]);
+ });
+
+ test.each([
+ ['cli/node_modules/@inkeep/open-knowledge-native-config/target/release/CACHEDIR.TAG', 'cargo'],
+ ['app.asar/src/main/index.ts', 'outside out/'],
+ ['app.asar/tests/e2e/app.e2e.ts', 'outside out/'],
+ ['app.asar/electron-builder.linux.yml', 'outside out/'],
+ ['app.asar/out/renderer/index.html', 'renderer'],
+ ['cli/dist/public/index.html', 'web app'],
+ ['app.asar.unpacked/node_modules/@inkeep/open-knowledge/dist/public/index.html', 'web app'],
+ [
+ 'app.asar.unpacked/node_modules/@inkeep/open-knowledge-native-config/index.js',
+ 'native-config',
+ ],
+ ['app.asar/node_modules/@inkeep/open-knowledge-core/src/index.ts', 'sources'],
+ ])('flags %s', (path, reasonFragment) => {
+ const hits = findForbiddenBundlePaths([...SOUND_PATHS, path]);
+ expect(hits).toHaveLength(1);
+ expect(hits[0].reason).toContain(reasonFragment);
+ expect(hits[0].example).toBe(path);
+ });
+});
+
+describe('findMissingBundlePaths', () => {
+ test('passes a sound bundle', () => {
+ expect(findMissingBundlePaths(SOUND_PATHS)).toEqual([]);
+ });
+
+ test.each([
+ ['app.asar/package.json', 'app.asar'],
+ [`${LIBRARY_NATIVE}/index.js`, "main process's native-config loader"],
+ [`${LIBRARY_NATIVE}/native-config.darwin-arm64.node`, "main process's native-config addon"],
+ ['cli/dist/native/index.js', "bundled CLI's native-config loader"],
+ ['cli/dist/native/native-config.linux-x64-gnu.node', "bundled CLI's native-config addon"],
+ ])('reports a bundle without %s', (dropped, reasonFragment) => {
+ const missing = findMissingBundlePaths(SOUND_PATHS.filter((p) => p !== dropped));
+ expect(missing).toHaveLength(1);
+ expect(missing[0]).toContain(reasonFragment);
+ });
+
+ test('reports an addon left inside app.asar instead of unpacked', () => {
+ const packedAddon = SOUND_PATHS.map((p) =>
+ p.endsWith('.darwin-arm64.node') ? p.replace('app.asar.unpacked/', 'app.asar/') : p,
+ );
+ expect(findMissingBundlePaths(packedAddon)).toEqual([
+ "the main process's native-config addon, unpacked",
+ ]);
+ });
+});
+
+describe('assertPackagedBundle', () => {
+ test('passes a packed bundle laid out the way its processes load it', () => {
+ const resources = packResources({ asarFiles: SOUND_ASAR, diskFiles: SOUND_DISK });
+ expect(() => assertPackagedBundle(resources)).not.toThrow();
+ });
+
+ test('fails a packed bundle on dead weight inside app.asar and beside it', () => {
+ const resources = packResources({
+ asarFiles: [...SOUND_ASAR, 'out/renderer/index.html', 'tests/e2e/app.e2e.ts'],
+ diskFiles: [...SOUND_DISK, 'cli/dist/public/index.html'],
+ });
+ expect(() => assertPackagedBundle(resources)).toThrow(
+ /Resources\/app\.asar\/tests[\s\S]*out\/renderer\/index\.html[\s\S]*cli\/dist\/public\/index\.html/,
+ );
+ });
+
+ test('fails a bundle with no app.asar', () => {
+ const resources = packResources({ diskFiles: SOUND_DISK });
+ expect(() => assertPackagedBundle(resources)).toThrow(/lacks app\.asar with its package\.json/);
+ });
+});
diff --git a/packages/desktop/tests/unit/electron-builder-cli-native-deps.test.ts b/packages/desktop/tests/unit/electron-builder-cli-native-deps.test.ts
index 9cc72b826..a7049dfcf 100644
--- a/packages/desktop/tests/unit/electron-builder-cli-native-deps.test.ts
+++ b/packages/desktop/tests/unit/electron-builder-cli-native-deps.test.ts
@@ -88,15 +88,6 @@ function readExtraResources(platform?: 'mac' | 'win' | 'linux'): ExtraResourceRu
}
}
-function readAsarUnpack(): string[] {
- try {
- const cfg = parse(readFileSync(builderYml, 'utf8')) as { asarUnpack?: string[] };
- return cfg.asarUnpack ?? [];
- } catch {
- return [];
- }
-}
-
function asFilterList(filter: string[] | string | undefined): string[] {
if (Array.isArray(filter)) return filter;
return filter ? [filter] : [];
@@ -197,10 +188,6 @@ describe('@inkeep/open-knowledge-native-config ships its napi loader + platform
).toBe(true);
});
- test('asarUnpack unpacks the addon for the in-process desktop main consumer', () => {
- expect(readAsarUnpack()).toContain(`**/${NATIVE_CONFIG}/**`);
- });
-
test('the addon source dir exists at the extraResources `from` path', () => {
expect(existsSync(nativeConfigDir)).toBe(true);
expect(existsSync(resolve(nativeConfigDir, 'package.json'))).toBe(true);
diff --git a/packages/desktop/tests/unit/windows-package-native-guards.test.ts b/packages/desktop/tests/unit/windows-package-native-guards.test.ts
index 01f7e5571..07802d12e 100644
--- a/packages/desktop/tests/unit/windows-package-native-guards.test.ts
+++ b/packages/desktop/tests/unit/windows-package-native-guards.test.ts
@@ -12,7 +12,12 @@ import { tmpdir } from 'node:os';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { afterEach, describe, expect, test } from 'vitest';
-import { MAX_ASAR_HEADER_BYTES, readAsarHeader } from '../../scripts/lib/asar-header.mjs';
+import {
+ listAsarHeaderPaths,
+ MAX_ASAR_HEADER_BYTES,
+ readAsarHeader,
+} from '../../scripts/lib/asar-header.mjs';
+import { writeSyntheticAsar } from '../support/synthetic-asar.test-helper.ts';
const __dirname = dirname(fileURLToPath(import.meta.url));
const desktopRoot = resolve(__dirname, '../..');
@@ -68,33 +73,6 @@ function walkFiles(root: string): string[] {
return found.sort();
}
-type AsarDirNode = { files?: Record<string, unknown> };
-
-function asarEntryPaths(header: AsarDirNode): string[] {
- const paths: string[] = [];
- const visit = (node: AsarDirNode, prefix: string): void => {
- for (const [name, entry] of Object.entries(node.files ?? {})) {
- const path = prefix === '' ? name : `${prefix}/${name}`;
- paths.push(path);
- if (typeof entry === 'object' && entry !== null && 'files' in entry) {
- visit(entry as AsarDirNode, path);
- }
- }
- };
- visit(header, '');
- return paths.sort();
-}
-
-function writeSyntheticAsar(path: string, header: object): void {
- const json = Buffer.from(JSON.stringify(header), 'utf8');
- const prefix = Buffer.alloc(16);
- prefix.writeUInt32LE(4, 0);
- prefix.writeUInt32LE(json.length + 8, 4);
- prefix.writeUInt32LE(json.length + 4, 8);
- prefix.writeUInt32LE(json.length, 12);
- writeFileSync(path, Buffer.concat([prefix, json]));
-}
-
const fixtureDirs: string[] = [];
afterEach(() => {
for (const dir of fixtureDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
@@ -142,7 +120,7 @@ describe('Windows package native guard helpers', () => {
},
},
});
- expect(asarEntryPaths(readAsarHeader(asar) as AsarDirNode)).toEqual([
+ expect(listAsarHeaderPaths(readAsarHeader(asar))).toEqual([
'node_modules',
'node_modules/node-pty',
'node_modules/node-pty/package.json',
@@ -225,7 +203,7 @@ describe.skipIf(packageDir === null)('packaged Windows node-pty payload', () =>
});
test('app.asar carries node-pty but none of the pruned trees', () => {
- const entries = asarEntryPaths(readAsarHeader(appAsarPath));
+ const entries = listAsarHeaderPaths(readAsarHeader(appAsarPath));
const nodePtyEntries = entries.filter((entry) => entry.startsWith('node_modules/node-pty/'));
expect(nodePtyEntries.length, 'node-pty absent from app.asar').toBeGreaterThan(0);
const offenders = nodePtyEntries.filter(