Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.plistindex 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 waswritten to introduce — without it, LaunchServices keys on the spawndiff --git a/packages/desktop/electron-builder.yml b/packages/desktop/electron-builder.ymlindex 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.plistto: Frameworks/OpenKnowledge Server.app/Contents/Info.plistdiff --git a/packages/desktop/resources/cli/bin/ok.sh b/packages/desktop/resources/cli/bin/ok.shindex 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" ]; thenfi# 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" inmcp|start)diff --git a/packages/desktop/src/main/resolve-detached-spawn-args.test.ts b/packages/desktop/src/main/resolve-detached-spawn-args.test.tsindex 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.tsindex 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.tsindex 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-knoimport {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 / afterPacexpect(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(