Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Fix OpenKnowledge Beta failing to open projects on macOS (#5238)

Andrew Mikofalvy452eb50593c4
diff --git a/.changeset/beta-server-helper-path.md b/.changeset/beta-server-helper-path.md
new file mode 100644
index 000000000..25476a80a
--- /dev/null
+++ b/.changeset/beta-server-helper-path.md
@@ -0,0 +1,6 @@
+---
+"@inkeep/open-knowledge": patch
+"@inkeep/open-knowledge-desktop": patch
+---
+
+OpenKnowledge Beta on macOS can open and create projects again.
diff --git a/packages/cli/src/commands/self-spawn.test.ts b/packages/cli/src/commands/self-spawn.test.ts
index 7c0333b55..3f7780bee 100644
--- a/packages/cli/src/commands/self-spawn.test.ts
+++ b/packages/cli/src/commands/self-spawn.test.ts
@@ -106,6 +106,18 @@ describe('resolveSelfSpawn', () => {
expect(warnSpy).not.toHaveBeenCalled();
});
+ it('packaged-darwin Beta execPath → command is the Beta-named helper-bundle binary', () => {
+ const betaApp = '/Applications/OpenKnowledge Beta.app';
+ const betaHelper = `${betaApp}/Contents/Frameworks/OpenKnowledge Beta Server.app/Contents/MacOS/OpenKnowledge Beta Helper`;
+ const result = resolveSelfSpawn({
+ execPath: `${betaApp}/Contents/MacOS/OpenKnowledge Beta`,
+ platform: 'darwin',
+ argv: ['runtime', PACKAGED_ENTRY],
+ exists: (p) => p === betaHelper,
+ });
+ expect(result.command).toBe(betaHelper);
+ });
+
it('packaged-darwin Electron execPath + helper ABSENT → command stays process.execPath', () => {
const result = resolveSelfSpawn({
execPath: PACKAGED_EXEC,
diff --git a/packages/core/src/helper-bundle.test.ts b/packages/core/src/helper-bundle.test.ts
index 753019b09..9a7133b94 100644
--- a/packages/core/src/helper-bundle.test.ts
+++ b/packages/core/src/helper-bundle.test.ts
@@ -1,4 +1,5 @@
import { describe, expect, test } from 'vitest';
+import { DESKTOP_PRODUCTS } from './constants/product.ts';
import {
HELPER_BUNDLE_NAME,
HELPER_EXECUTABLE_NAME,
@@ -20,4 +21,22 @@ describe('resolveHelperBundleBinary', () => {
`/Users/alex/Applications/OpenKnowledge.app/Contents/Frameworks/${HELPER_BUNDLE_NAME}/Contents/MacOS/${HELPER_EXECUTABLE_NAME}`,
);
});
+
+ test('keys off the executable, so a renamed app bundle still resolves', () => {
+ expect(
+ resolveHelperBundleBinary('/Applications/Renamed.app/Contents/MacOS/OpenKnowledge Beta'),
+ ).toBe(
+ '/Applications/Renamed.app/Contents/Frameworks/OpenKnowledge Beta Server.app/Contents/MacOS/OpenKnowledge Beta Helper',
+ );
+ });
+
+ test.each(Object.values(DESKTOP_PRODUCTS))(
+ 'matches the layout afterPack writes for $productName',
+ ({ productName }) => {
+ const app = `/Applications/${productName}.app`;
+ expect(resolveHelperBundleBinary(`${app}/Contents/MacOS/${productName}`)).toBe(
+ `${app}/Contents/Frameworks/${productName} Server.app/Contents/MacOS/${productName} Helper`,
+ );
+ },
+ );
});
diff --git a/packages/core/src/helper-bundle.ts b/packages/core/src/helper-bundle.ts
index 047f9785a..d7370653f 100644
--- a/packages/core/src/helper-bundle.ts
+++ b/packages/core/src/helper-bundle.ts
@@ -1,16 +1,26 @@
import { posix as pathPosix } from 'node:path';
+import { PRODUCT_NAME } from './constants/product.ts';
-export const HELPER_BUNDLE_NAME = 'OpenKnowledge Server.app';
-export const HELPER_EXECUTABLE_NAME = 'OpenKnowledge Helper';
+function helperBundleName(productName: string): string {
+ return `${productName} Server.app`;
+}
+
+function helperExecutableName(productName: string): string {
+ return `${productName} Helper`;
+}
+
+export const HELPER_BUNDLE_NAME = helperBundleName(PRODUCT_NAME);
+export const HELPER_EXECUTABLE_NAME = helperExecutableName(PRODUCT_NAME);
export function resolveHelperBundleBinary(parentExecPath: string): string {
+ const productName = pathPosix.basename(parentExecPath);
return pathPosix.join(
pathPosix.dirname(parentExecPath),
'..',
'Frameworks',
- HELPER_BUNDLE_NAME,
+ helperBundleName(productName),
'Contents',
'MacOS',
- HELPER_EXECUTABLE_NAME,
+ helperExecutableName(productName),
);
}
diff --git a/packages/desktop/build/helper-bundle/Info.plist b/packages/desktop/build/helper-bundle/Info.plist
index ead815071..fc4bd772a 100644
--- a/packages/desktop/build/helper-bundle/Info.plist
+++ b/packages/desktop/build/helper-bundle/Info.plist
@@ -1,20 +1,12 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<!--
- Helper bundle Info.plist for `OpenKnowledge Server.app`, the detached-
- server helper bundle inside `OpenKnowledge.app/Contents/Frameworks/`.
-
- `CFBundleExecutable` MUST stay byte-for-byte `OpenKnowledge Helper` —
- matches Electron's canonical generic-helper basename. The helper stub
- cloned into this bundle by `scripts/afterPack.mjs` inspects its own
- `_NSGetExecutablePath()` basename early in boot and silently SIGTRAPs
- (exit 133, empty stderr) for any other name, including descriptive
- choices ("OpenKnowledge Server") or invented suffixes ("Helper
- (Server)") not in Electron's hardcoded {generic, Renderer, GPU,
- Plugin} type set. The bundle directory name (`OpenKnowledge
- Server.app`) is free to be descriptive — only the executable
- basename is load-bearing. Runtime guard:
- `tests/integration/packaged-helper-runs-as-node.test.ts`.
+ UPSTREAM([email protected]): the helper stub `scripts/afterPack.mjs` clones
+ into this bundle reads its own `_NSGetExecutablePath()` basename early in
+ boot and silently SIGTRAPs (exit 133, empty stderr) unless it is
+ `<productName> Helper`, so `CFBundleExecutable` carries that name
+ (Stable here; `scripts/desktop-variant-config.ts` rewrites it for Beta).
+ Runtime guard: `tests/integration/packaged-helper-runs-as-node.test.ts`.
`LSUIElement=true` is the Dock-suppression key that PR #1290 was
written to introduce — without it, LaunchServices keys on the spawn
diff --git a/packages/desktop/electron-builder.yml b/packages/desktop/electron-builder.yml
index 7c962e21a..fd874df89 100644
--- a/packages/desktop/electron-builder.yml
+++ b/packages/desktop/electron-builder.yml
@@ -334,13 +334,10 @@ mac:
# declares `LSUIElement=true` so macOS LaunchServices launches the
# spawned server process without a Dock tile — without this, the
# re-exec into the parent's MacOS binary triggers LaunchServices to
- # pin a stuck "exec" Dock placeholder for the child's lifetime. The
- # MacOS binary slot at
- # `Frameworks/OpenKnowledge Server.app/Contents/MacOS/OpenKnowledge Helper`
- # is populated by `scripts/afterPack.mjs` (clones the Electron Helper
- # stub for its correct rpath). The executable basename MUST stay
- # `OpenKnowledge Helper` (Electron's canonical generic-helper name) —
- # see `src/main/resolve-detached-spawn-args.ts` for the SIGTRAP cause.
+ # pin a stuck "exec" Dock placeholder for the child's lifetime.
+ # UPSTREAM([email protected]): the helper binary afterPack clones into
+ # `<productName> Server.app/Contents/MacOS` SIGTRAPs unless it is named
+ # `<productName> Helper`; see `build/helper-bundle/Info.plist`.
extraFiles:
- from: build/helper-bundle/Info.plist
to: Frameworks/OpenKnowledge Server.app/Contents/Info.plist
diff --git a/packages/desktop/resources/cli/bin/ok.sh b/packages/desktop/resources/cli/bin/ok.sh
index 4e8c818bc..c87458b40 100755
--- a/packages/desktop/resources/cli/bin/ok.sh
+++ b/packages/desktop/resources/cli/bin/ok.sh
@@ -35,8 +35,8 @@ if [ ! -f "$CLI" ] || [ ! -x "$ELECTRON" ]; then
fi
# UPSTREAM([email protected]): an ELECTRON_RUN_AS_NODE boot reads its own basename
-# via _NSGetExecutablePath() and SIGTRAPs on anything but "OpenKnowledge
-# Helper", so the executable literal below is fixed by Electron, not by us.
+# via _NSGetExecutablePath() and SIGTRAPs on anything but "<product> Helper",
+# so the executable name below is fixed by Electron, not by us.
RUNTIME="$ELECTRON"
case "$1" in
mcp|start)
diff --git a/packages/desktop/src/main/resolve-detached-spawn-args.test.ts b/packages/desktop/src/main/resolve-detached-spawn-args.test.ts
index 5f2ed3293..d3511c139 100644
--- a/packages/desktop/src/main/resolve-detached-spawn-args.test.ts
+++ b/packages/desktop/src/main/resolve-detached-spawn-args.test.ts
@@ -45,6 +45,16 @@ describe('resolveDetachedSpawnArgs', () => {
expect(file).not.toBe(PARENT_EXEC);
});
+ test('darwin packaged Beta → file targets the Beta-named helper bundle the build produces', () => {
+ const betaApp = '/Applications/OpenKnowledge Beta.app';
+ const { file } = resolveDetachedSpawnArgs(
+ makeInput({ parentExecPath: `${betaApp}/Contents/MacOS/OpenKnowledge Beta` }),
+ );
+ expect(file).toBe(
+ `${betaApp}/Contents/Frameworks/OpenKnowledge Beta Server.app/Contents/MacOS/OpenKnowledge Beta Helper`,
+ );
+ });
+
test.each([
['darwin', false],
['linux', true],
diff --git a/packages/desktop/tests/integration/packaged-helper-runs-as-node.test.ts b/packages/desktop/tests/integration/packaged-helper-runs-as-node.test.ts
index 77031b4e7..2aa5447b1 100644
--- a/packages/desktop/tests/integration/packaged-helper-runs-as-node.test.ts
+++ b/packages/desktop/tests/integration/packaged-helper-runs-as-node.test.ts
@@ -1,96 +1,115 @@
import { spawnSync } from 'node:child_process';
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
-import {
- HELPER_BUNDLE_NAME,
- HELPER_EXECUTABLE_NAME,
-} from '@inkeep/open-knowledge-core/helper-bundle';
+import { resolveHelperBundleBinary } from '@inkeep/open-knowledge-core/helper-bundle';
import { describe, expect, test } from 'vitest';
const HERE = dirname(fileURLToPath(import.meta.url));
const desktopRoot = resolve(HERE, '../..');
const distDesktopDir = resolve(desktopRoot, 'dist-desktop');
-function findPackagedHelperBinary(): string | null {
- if (!existsSync(distDesktopDir)) return null;
- let macSubdirs: readonly string[];
+function listDir(path: string): readonly string[] {
try {
- macSubdirs = readdirSync(distDesktopDir).filter((name) => name.startsWith('mac-'));
+ return readdirSync(path);
} catch {
- return null;
+ return [];
}
- for (const subdir of macSubdirs) {
- const candidate = join(
- distDesktopDir,
- subdir,
- 'OpenKnowledge.app',
- 'Contents/Frameworks',
- HELPER_BUNDLE_NAME,
- 'Contents/MacOS',
- HELPER_EXECUTABLE_NAME,
- );
- if (existsSync(candidate)) return candidate;
- }
- return null;
+}
+
+function bundleExecutable(bundle: string): string | null {
+ const plistPath = join(bundle, 'Contents/Info.plist');
+ if (!existsSync(plistPath)) return null;
+ const name = readFileSync(plistPath, 'utf8').match(
+ /<key>CFBundleExecutable<\/key>\s*<string>([^<]*)<\/string>/,
+ )?.[1];
+ return name === undefined ? null : join(bundle, 'Contents/MacOS', name);
+}
+
+interface PackagedApp {
+ readonly app: string;
+ readonly executable: string | null;
+ readonly helper: string | null;
+}
+
+function findPackagedApps(): readonly PackagedApp[] {
+ return listDir(distDesktopDir)
+ .filter((name) => name.startsWith('mac-'))
+ .flatMap((subdir) =>
+ listDir(join(distDesktopDir, subdir))
+ .filter((name) => name.endsWith('.app'))
+ .map((name) => join(distDesktopDir, subdir, name)),
+ )
+ .map((app) => {
+ const frameworks = join(app, 'Contents/Frameworks');
+ const servers = listDir(frameworks).filter((name) => name.endsWith(' Server.app'));
+ const helper = servers.length === 1 ? bundleExecutable(join(frameworks, servers[0])) : null;
+ return { app, executable: bundleExecutable(app), helper };
+ });
}
const haveDarwin = process.platform === 'darwin';
-const packagedHelperBinary = haveDarwin ? findPackagedHelperBinary() : null;
-const havePackagedBuild = packagedHelperBinary !== null;
+const packagedApps = haveDarwin ? findPackagedApps() : [];
describe('packaged helper binary runs under ELECTRON_RUN_AS_NODE=1', () => {
test('test environment gate (packaged build present)', (ctx) => {
ctx.skip(!haveDarwin, `darwin-only test; platform=${process.platform}`);
ctx.skip(
- !havePackagedBuild,
- `no packaged helper binary found under ${distDesktopDir}/mac-<arch>/OpenKnowledge.app/... — run ` +
+ packagedApps.length === 0,
+ `no packaged app found under ${distDesktopDir}/mac-<arch>/ — run ` +
`\`pnpm exec electron-builder --dir --publish never\` (or \`okdesk\`) to enable this test`,
);
- expect(existsSync(packagedHelperBinary as string)).toBe(true);
+ expect(packagedApps.length).toBeGreaterThan(0);
});
- test.skipIf(!havePackagedBuild)(
- 'helper binary exits 0 with stdout under ELECTRON_RUN_AS_NODE=1 (no SIGTRAP)',
- () => {
- const helperPath = packagedHelperBinary as string;
- const result = spawnSync(
- helperPath,
- ['-e', 'console.log("ok-helper-node-mode", process.versions.node)'],
- {
- env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
- encoding: 'utf8',
- timeout: 10_000,
- },
- );
+ describe.each(packagedApps.map((packaged) => [packaged.app, packaged] as const))(
+ '%s',
+ (_app, packaged) => {
+ test('carries exactly one Server.app helper with an existing executable', () => {
+ expect(packaged.helper, `${packaged.app} has no usable Server.app helper`).not.toBeNull();
+ expect(existsSync(packaged.helper as string)).toBe(true);
+ });
- expect({
- status: result.status,
- signal: result.signal,
- stdout: result.stdout,
- stderrTail: result.stderr.slice(-200),
- }).toEqual({
- status: 0,
- signal: null,
- stdout: expect.stringMatching(/ok-helper-node-mode\s+\d+\.\d+\.\d+/),
- stderrTail: '',
+ test('the spawn-site resolver lands on that helper', () => {
+ expect(packaged.executable).not.toBeNull();
+ expect(resolveHelperBundleBinary(packaged.executable as string)).toBe(packaged.helper);
});
- },
- );
- test.skipIf(!havePackagedBuild)(
- 'helper binary loads Electron Framework via @rpath without dyld errors',
- () => {
- const helperPath = packagedHelperBinary as string;
- const result = spawnSync(helperPath, ['-e', 'process.exit(0)'], {
- env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
- encoding: 'utf8',
- timeout: 10_000,
+ test('helper binary exits 0 with stdout under ELECTRON_RUN_AS_NODE=1 (no SIGTRAP)', () => {
+ const result = spawnSync(
+ packaged.helper as string,
+ ['-e', 'console.log("ok-helper-node-mode", process.versions.node)'],
+ {
+ env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
+ encoding: 'utf8',
+ timeout: 10_000,
+ },
+ );
+
+ expect({
+ status: result.status,
+ signal: result.signal,
+ stdout: result.stdout,
+ stderrTail: result.stderr.slice(-200),
+ }).toEqual({
+ status: 0,
+ signal: null,
+ stdout: expect.stringMatching(/ok-helper-node-mode\s+\d+\.\d+\.\d+/),
+ stderrTail: '',
+ });
});
- expect(result.stderr).not.toContain('Library not loaded');
- expect(result.stderr).not.toContain('Unable to find helper app');
- expect(result.status).toBe(0);
+ test('helper binary loads Electron Framework via @rpath without dyld errors', () => {
+ const result = spawnSync(packaged.helper as string, ['-e', 'process.exit(0)'], {
+ env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
+ encoding: 'utf8',
+ timeout: 10_000,
+ });
+
+ expect(result.stderr).not.toContain('Library not loaded');
+ expect(result.stderr).not.toContain('Unable to find helper app');
+ expect(result.status).toBe(0);
+ });
},
);
});
diff --git a/packages/desktop/tests/unit/helper-bundle-name-agreement.test.ts b/packages/desktop/tests/unit/helper-bundle-name-agreement.test.ts
index 9cf2ebef5..698ec13f4 100644
--- a/packages/desktop/tests/unit/helper-bundle-name-agreement.test.ts
+++ b/packages/desktop/tests/unit/helper-bundle-name-agreement.test.ts
@@ -5,8 +5,15 @@ import { DESKTOP_PRODUCTS, desktopWindowsExecutableName } from '@inkeep/open-kno
import {
HELPER_BUNDLE_NAME,
HELPER_EXECUTABLE_NAME,
+ resolveHelperBundleBinary,
} from '@inkeep/open-knowledge-core/helper-bundle';
import { describe, expect, test } from 'vitest';
+import {
+ createVariantBuilderConfig,
+ createVariantHelperInfo,
+ parseBuilderConfig,
+} from '../../scripts/desktop-variant-config.ts';
+import { DESKTOP_VARIANTS, type DesktopVariantName } from '../../src/shared/desktop-variant.ts';
const __dirname = dirname(fileURLToPath(import.meta.url));
const desktopRoot = resolve(__dirname, '../..');
@@ -52,6 +59,41 @@ describe('helper-bundle name agreement across spawn site / Info.plist / afterPac
expect(afterPack).toMatch(/`\$\{appName\} Server\.app`/);
});
+ test.each(Object.keys(DESKTOP_VARIANTS) as DesktopVariantName[])(
+ 'the spawn-site resolver finds the helper the %s packaging writes',
+ (variantName) => {
+ const config = createVariantBuilderConfig(
+ parseBuilderConfig(readFileSync(electronBuilderYmlPath, 'utf8')),
+ variantName,
+ {
+ includePath: 'installer.nsh',
+ postInstallPath: 'deb-postinst.sh',
+ postRemovePath: 'deb-postrm.sh',
+ localEntitlementsPath: 'entitlements.mac.local.plist',
+ helperInfoPath: 'helper-Info.plist',
+ profileAvailable: false,
+ },
+ '0.0.0-beta.0',
+ );
+ const helperInfoTarget = config.mac.extraFiles.find(
+ (entry) => entry.from === 'helper-Info.plist',
+ )?.to;
+ const bundleDir = helperInfoTarget?.match(
+ /^(Frameworks\/[^/]+\.app)\/Contents\/Info\.plist$/,
+ )?.[1];
+ const executable = extractPlistString(
+ createVariantHelperInfo(readFileSync(helperPlistPath, 'utf8'), variantName),
+ 'CFBundleExecutable',
+ );
+ expect(bundleDir).toBeDefined();
+ expect(executable).not.toBeNull();
+ const app = `/Applications/${config.productName}.app`;
+ expect(resolveHelperBundleBinary(`${app}/Contents/MacOS/${config.productName}`)).toBe(
+ `${app}/Contents/${bundleDir}/Contents/MacOS/${executable}`,
+ );
+ },
+ );
+
test('electron-builder.yml extraFiles `to:` value references HELPER_BUNDLE_NAME (not just a YAML comment)', () => {
const yml = readFileSync(electronBuilderYmlPath, 'utf8');
expect(yml).toMatch(