Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.ymlindex 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.mjsindex 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.mjsnew file mode 100644index 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.mjsindex 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.mdindex 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.tsnew file mode 100644index 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.mjsindex 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.mjsnew file mode 100644index 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.tsindex 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.tsindex 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(