Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Take the OK package graphs off the utility entry's pre-listener path (#4866)

Nick Gomezd7e80c60a966
diff --git a/.changeset/desktop-utility-init-defer-graphs.md b/.changeset/desktop-utility-init-defer-graphs.md
new file mode 100644
index 000000000..01bd0d5be
--- /dev/null
+++ b/.changeset/desktop-utility-init-defer-graphs.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge-desktop": patch
+---
+
+In unpackaged desktop runs, a project server that fails to load its OpenKnowledge packages now shows that error in the "Unable to open project" dialog instead of only an exit code. Installed apps open projects through a separate path and are unaffected.
diff --git a/knip.config.ts b/knip.config.ts
index 5b8951125..6a38348d8 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -156,6 +156,7 @@ export default {
'src/utility/pty-host.ts',
'src/**/*.test.ts',
'src/**/*.typelock.ts',
+ 'src/utility/server-entry-load-probe.fixture.test-helper.ts',
'scripts/*.mjs',
'tests/**/*.test.ts',
'tests/**/*.test.mjs',
diff --git a/packages/desktop/src/utility/server-entry-load-probe.fixture.test-helper.ts b/packages/desktop/src/utility/server-entry-load-probe.fixture.test-helper.ts
new file mode 100644
index 000000000..4d90fb4ae
--- /dev/null
+++ b/packages/desktop/src/utility/server-entry-load-probe.fixture.test-helper.ts
@@ -0,0 +1,31 @@
+export type LoadProbeFixtureMode = 'import-before-listener' | 'listener-before-import';
+
+const LOAD_PROBE_FIXTURE_MODE_ENV = 'OK_UTILITY_LOAD_PROBE_FIXTURE_MODE';
+
+const mode = process.env[LOAD_PROBE_FIXTURE_MODE_ENV];
+
+if (mode !== 'import-before-listener' && mode !== 'listener-before-import') {
+ throw new Error(
+ `${LOAD_PROBE_FIXTURE_MODE_ENV} must be import-before-listener or listener-before-import, got ${JSON.stringify(mode)}`,
+ );
+}
+
+function registerParentPortListener(): void {
+ const parentPort = (
+ process as NodeJS.Process & {
+ parentPort?: { on(event: 'message', handler: (event: { data: unknown }) => void): void };
+ }
+ ).parentPort;
+ if (!parentPort) {
+ throw new Error('load-probe fixture requires process.parentPort to be installed by the probe');
+ }
+ parentPort.on('message', () => {});
+}
+
+if (mode === 'import-before-listener') {
+ await import('@inkeep/open-knowledge-core/shadow-repo-layout');
+ registerParentPortListener();
+} else {
+ registerParentPortListener();
+ await import('@inkeep/open-knowledge-core/shadow-repo-layout');
+}
diff --git a/packages/desktop/src/utility/server-entry-load-probe.test-helper.ts b/packages/desktop/src/utility/server-entry-load-probe.test-helper.ts
new file mode 100644
index 000000000..68f84b3d0
--- /dev/null
+++ b/packages/desktop/src/utility/server-entry-load-probe.test-helper.ts
@@ -0,0 +1,113 @@
+import { writeFileSync } from 'node:fs';
+import { registerHooks } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+interface ProbeResolveEvent {
+ seq: number;
+ specifier: string;
+ url: string;
+}
+
+interface ProbeLoadEvent {
+ seq: number;
+ url: string;
+}
+
+export interface UtilityLoadProbeRecord {
+ entryPath: string;
+ parentPortListenerRegisteredAtSeq: number | null;
+ totalEventCount: number;
+ bareSpecifierResolves: ProbeResolveEvent[];
+ moduleLoads: ProbeLoadEvent[];
+ parentPortMessagesPosted: number;
+ signalsAttemptedByEntry: { pid: number; signal: string | number | undefined }[];
+ entryImportFailure: { message: string; code: string | undefined } | null;
+}
+
+const entryPath = process.argv[2];
+const recordPath = process.argv[3];
+
+if (entryPath === undefined || recordPath === undefined) {
+ process.stderr.write(
+ 'usage: node server-entry-load-probe.test-helper.ts <entryPath> <recordPath>\n',
+ );
+ process.exit(2);
+}
+
+let seq = 0;
+const bareSpecifierResolves: ProbeResolveEvent[] = [];
+const moduleLoads: ProbeLoadEvent[] = [];
+
+function isBareSpecifier(specifier: string): boolean {
+ return (
+ !specifier.startsWith('.') &&
+ !specifier.startsWith('/') &&
+ !specifier.startsWith('node:') &&
+ !specifier.startsWith('file:') &&
+ !specifier.startsWith('data:')
+ );
+}
+
+registerHooks({
+ resolve(specifier, context, nextResolve) {
+ const resolved = nextResolve(specifier, context);
+ if (isBareSpecifier(specifier)) {
+ bareSpecifierResolves.push({ seq: seq++, specifier, url: resolved.url });
+ }
+ return resolved;
+ },
+ load(url, context, nextLoad) {
+ moduleLoads.push({ seq: seq++, url });
+ return nextLoad(url, context);
+ },
+});
+
+const signalsAttemptedByEntry: { pid: number; signal: string | number | undefined }[] = [];
+process.kill = ((pid: number, signal?: string | number) => {
+ signalsAttemptedByEntry.push({ pid, signal });
+ return true;
+}) as typeof process.kill;
+
+let parentPortListenerRegisteredAtSeq: number | null = null;
+let parentPortMessagesPosted = 0;
+
+const recordingParentPort = {
+ on(event: string, _handler: (event: { data: unknown }) => void): void {
+ if (event === 'message' && parentPortListenerRegisteredAtSeq === null) {
+ parentPortListenerRegisteredAtSeq = seq;
+ }
+ },
+ postMessage(_value: unknown): void {
+ parentPortMessagesPosted += 1;
+ },
+};
+
+Object.defineProperty(process, 'parentPort', {
+ value: recordingParentPort,
+ configurable: true,
+ writable: true,
+});
+
+let entryImportFailure: UtilityLoadProbeRecord['entryImportFailure'] = null;
+try {
+ await import(pathToFileURL(entryPath).href);
+} catch (err) {
+ entryImportFailure = {
+ message: err instanceof Error ? err.message : String(err),
+ code: (err as NodeJS.ErrnoException | undefined)?.code,
+ };
+}
+
+const record: UtilityLoadProbeRecord = {
+ entryPath,
+ parentPortListenerRegisteredAtSeq,
+ totalEventCount: seq,
+ bareSpecifierResolves,
+ moduleLoads,
+ parentPortMessagesPosted,
+ signalsAttemptedByEntry,
+ entryImportFailure,
+};
+
+writeFileSync(recordPath, JSON.stringify(record), 'utf-8');
+process.exit(0);
diff --git a/packages/desktop/src/utility/server-entry.readiness-path.test.ts b/packages/desktop/src/utility/server-entry.readiness-path.test.ts
new file mode 100644
index 000000000..fbea5ec02
--- /dev/null
+++ b/packages/desktop/src/utility/server-entry.readiness-path.test.ts
@@ -0,0 +1,144 @@
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { afterAll, describe, expect, test } from 'vitest';
+import type { UtilityLoadProbeRecord } from './server-entry-load-probe.test-helper.ts';
+
+const PROBE_COUNT = 3;
+const SUITE_LIVENESS_BUDGET_MS = 90_000;
+const PROBE_LIVENESS_TIMEOUT_MS = Math.floor(SUITE_LIVENESS_BUDGET_MS / PROBE_COUNT);
+const TEST_LIVENESS_TIMEOUT_MS = PROBE_LIVENESS_TIMEOUT_MS + 5_000;
+const OK_PACKAGE_SPECIFIER_PREFIX = '@inkeep/open-knowledge';
+const OK_DEBUG_ENV_PREFIX = 'OK_DEBUG_';
+
+const utilityDir = fileURLToPath(new URL('.', import.meta.url));
+const probePath = join(utilityDir, 'server-entry-load-probe.test-helper.ts');
+const fixturePath = join(utilityDir, 'server-entry-load-probe.fixture.test-helper.ts');
+const productionEntryPath = join(utilityDir, 'server-entry.ts');
+
+const probeSandboxes: string[] = [];
+
+afterAll(() => {
+ for (const dir of probeSandboxes) rmSync(dir, { recursive: true, force: true });
+});
+
+function runLoadProbe(
+ entryPath: string,
+ extraEnv: Record<string, string> = {},
+): UtilityLoadProbeRecord {
+ const sandbox = mkdtempSync(join(tmpdir(), 'ok-utility-load-probe-'));
+ probeSandboxes.push(sandbox);
+ const recordPath = join(sandbox, 'record.json');
+ const scrubbed: Record<string, string | undefined> = {};
+ for (const name of Object.keys(process.env)) {
+ if (name.startsWith(OK_DEBUG_ENV_PREFIX)) scrubbed[name] = undefined;
+ }
+ const env: Record<string, string | undefined> = {
+ ...process.env,
+ ...scrubbed,
+ HOME: sandbox,
+ USERPROFILE: sandbox,
+ ...extraEnv,
+ };
+ const spawned = spawnSync(process.execPath, [probePath, entryPath, recordPath], {
+ encoding: 'utf-8',
+ timeout: PROBE_LIVENESS_TIMEOUT_MS,
+ env,
+ });
+ if (spawned.status !== 0) {
+ throw new Error(
+ `load probe exited with status=${spawned.status} signal=${spawned.signal} for ${entryPath}\nstderr: ${spawned.stderr}`,
+ );
+ }
+ return JSON.parse(readFileSync(recordPath, 'utf-8')) as UtilityLoadProbeRecord;
+}
+
+function assertProbeImportedItsEntry(record: UtilityLoadProbeRecord): void {
+ if (record.entryImportFailure === null) return;
+ const unresolved = record.entryImportFailure.code === 'ERR_MODULE_NOT_FOUND';
+ const remedy = unresolved
+ ? ' This suite resolves @inkeep/open-knowledge, -core and -server through their production export conditions (dist), so those three packages must be built first. The desktop `test` turbo task supplies that through its `dependsOn: ["^build"]`; a bare `vitest run` in this package does not.'
+ : '';
+ throw new Error(
+ `the load probe could not import ${record.entryPath}: ${record.entryImportFailure.message} (code=${record.entryImportFailure.code}).${remedy}`,
+ );
+}
+
+function modulesLoadedBeforeParentPortListener(record: UtilityLoadProbeRecord): string[] {
+ assertProbeImportedItsEntry(record);
+ const listenerSeq = record.parentPortListenerRegisteredAtSeq;
+ if (listenerSeq === null) {
+ throw new Error(
+ `${record.entryPath} never registered a parent-port message listener, so there is no ordering to judge; the probe recorded ${record.totalEventCount} loader events`,
+ );
+ }
+ const urlToSpecifier = new Map<string, string>();
+ for (const resolved of record.bareSpecifierResolves) {
+ if (!urlToSpecifier.has(resolved.url)) urlToSpecifier.set(resolved.url, resolved.specifier);
+ }
+ const loadedEarly = new Set<string>();
+ for (const load of record.moduleLoads) {
+ if (load.seq >= listenerSeq) continue;
+ loadedEarly.add(urlToSpecifier.get(load.url) ?? load.url);
+ }
+ return [...loadedEarly].sort();
+}
+
+function okPackagesLoadedBeforeParentPortListener(record: UtilityLoadProbeRecord): string[] {
+ return modulesLoadedBeforeParentPortListener(record).filter((entry) =>
+ entry.startsWith(OK_PACKAGE_SPECIFIER_PREFIX),
+ );
+}
+
+describe('utility readiness critical path: what the process evaluates before it can act on a queued `init`', () => {
+ test(
+ 'the probe reports a violation for a fixture that finishes an @inkeep/open-knowledge import before registering its parent-port listener',
+ () => {
+ const record = runLoadProbe(fixturePath, {
+ OK_UTILITY_LOAD_PROBE_FIXTURE_MODE: 'import-before-listener',
+ });
+ assertProbeImportedItsEntry(record);
+ expect(record.parentPortListenerRegisteredAtSeq).toEqual(expect.any(Number));
+ expect(okPackagesLoadedBeforeParentPortListener(record)).toEqual([
+ '@inkeep/open-knowledge-core/shadow-repo-layout',
+ ]);
+ },
+ TEST_LIVENESS_TIMEOUT_MS,
+ );
+
+ test(
+ 'the probe reports no violation for a fixture that registers its parent-port listener before the same import',
+ () => {
+ const record = runLoadProbe(fixturePath, {
+ OK_UTILITY_LOAD_PROBE_FIXTURE_MODE: 'listener-before-import',
+ });
+ assertProbeImportedItsEntry(record);
+ expect(record.parentPortListenerRegisteredAtSeq).toEqual(expect.any(Number));
+ expect(record.bareSpecifierResolves.map((event) => event.specifier)).toContain(
+ '@inkeep/open-knowledge-core/shadow-repo-layout',
+ );
+ expect(okPackagesLoadedBeforeParentPortListener(record)).toEqual([]);
+ },
+ TEST_LIVENESS_TIMEOUT_MS,
+ );
+
+ test(
+ 'server-entry registers its parent-port message listener before it evaluates anything beyond its own cheap module scope',
+ () => {
+ const record = runLoadProbe(productionEntryPath);
+ expect(record.moduleLoads.map((load) => load.url)).toContain(
+ pathToFileURL(productionEntryPath).href,
+ );
+ expect(record.parentPortListenerRegisteredAtSeq).toEqual(expect.any(Number));
+ expect(modulesLoadedBeforeParentPortListener(record)).toEqual([
+ pathToFileURL(join(utilityDir, 'keyring-smoke.ts')).href,
+ pathToFileURL(productionEntryPath).href,
+ 'node:fs/promises',
+ 'node:path',
+ ]);
+ },
+ TEST_LIVENESS_TIMEOUT_MS,
+ );
+});
diff --git a/packages/desktop/src/utility/server-entry.test.ts b/packages/desktop/src/utility/server-entry.test.ts
index 140fc54f1..77f48bc6d 100644
--- a/packages/desktop/src/utility/server-entry.test.ts
+++ b/packages/desktop/src/utility/server-entry.test.ts
@@ -42,56 +42,56 @@ function writeLocalConfig(yaml: string) {
}
describe('resolveDesktopServerRuntime — scope-correct three-layer load', () => {
- test('honors a project-local server.allowExternal (the desktop consent path)', () => {
+ test('honors a project-local server.allowExternal (the desktop consent path)', async () => {
writeLocalConfig('server:\n allowExternal: true\n');
- const { serverRuntime, configValid } = resolveDesktopServerRuntime(testDir);
+ const { serverRuntime, configValid } = await resolveDesktopServerRuntime(testDir);
expect(configValid).toBe(true);
expect(serverRuntime.allowExternal).toBe(true);
});
- test('a committed server.allowExternal stays inert (clone-leak guard)', () => {
+ test('a committed server.allowExternal stays inert (clone-leak guard)', async () => {
writeProjectConfig('server:\n allowExternal: true\n');
- const { serverRuntime } = resolveDesktopServerRuntime(testDir);
+ const { serverRuntime } = await resolveDesktopServerRuntime(testDir);
expect(serverRuntime.allowExternal).toBe(false);
});
- test('project-local wins over a committed allowExternal in either direction', () => {
+ test('project-local wins over a committed allowExternal in either direction', async () => {
writeProjectConfig('server:\n allowExternal: true\n');
writeLocalConfig('server:\n allowExternal: false\n');
- expect(resolveDesktopServerRuntime(testDir).serverRuntime.allowExternal).toBe(false);
+ expect((await resolveDesktopServerRuntime(testDir)).serverRuntime.allowExternal).toBe(false);
rmSync(resolve(testDir, '.ok'), { recursive: true, force: true });
writeProjectConfig('server:\n allowExternal: false\n');
writeLocalConfig('server:\n allowExternal: true\n');
- expect(resolveDesktopServerRuntime(testDir).serverRuntime.allowExternal).toBe(true);
+ expect((await resolveDesktopServerRuntime(testDir)).serverRuntime.allowExternal).toBe(true);
});
- test('surfaces committed server.externalUrl + server.port (project scope, honest boot)', () => {
+ test('surfaces committed server.externalUrl + server.port (project scope, honest boot)', async () => {
writeProjectConfig('server:\n externalUrl: https://box.tailnet.ts.net\n port: 24550\n');
- const { serverRuntime } = resolveDesktopServerRuntime(testDir);
+ const { serverRuntime } = await resolveDesktopServerRuntime(testDir);
expect(serverRuntime.externalUrl).toBe('https://box.tailnet.ts.net');
expect(serverRuntime.port).toBe(24550);
});
- test('a project-local consent + committed externalUrl together admit the tunnel', () => {
+ test('a project-local consent + committed externalUrl together admit the tunnel', async () => {
writeProjectConfig('server:\n externalUrl: https://box.tailnet.ts.net\n port: 24550\n');
writeLocalConfig('server:\n allowExternal: true\n');
- const { serverRuntime } = resolveDesktopServerRuntime(testDir);
+ const { serverRuntime } = await resolveDesktopServerRuntime(testDir);
expect(serverRuntime.allowExternal).toBe(true);
expect(serverRuntime.externalUrl).toBe('https://box.tailnet.ts.net');
});
- test('degrades to schema defaults (consent forced off) on a schema-invalid config', () => {
+ test('degrades to schema defaults (consent forced off) on a schema-invalid config', async () => {
writeProjectConfig('server:\n port: "abc"\n');
- const { config, configValid, serverRuntime } = resolveDesktopServerRuntime(testDir);
+ const { config, configValid, serverRuntime } = await resolveDesktopServerRuntime(testDir);
expect(configValid).toBe(false);
expect(serverRuntime.allowExternal).toBe(false);
expect(serverRuntime.loopbackOnly).toBe(true);
expect(config.server?.allowExternal ?? false).toBe(false);
});
- test('no config files at all resolves to loopback-only defaults', () => {
- const { serverRuntime, configValid } = resolveDesktopServerRuntime(testDir);
+ test('no config files at all resolves to loopback-only defaults', async () => {
+ const { serverRuntime, configValid } = await resolveDesktopServerRuntime(testDir);
expect(configValid).toBe(true);
expect(serverRuntime.allowExternal).toBe(false);
expect(serverRuntime.loopbackOnly).toBe(true);
diff --git a/packages/desktop/src/utility/server-entry.ts b/packages/desktop/src/utility/server-entry.ts
index 3d9601308..feb1102df 100644
--- a/packages/desktop/src/utility/server-entry.ts
+++ b/packages/desktop/src/utility/server-entry.ts
@@ -1,25 +1,11 @@
import { rename, writeFile } from 'node:fs/promises';
import { isAbsolute, relative, resolve } from 'node:path';
-import {
- detectGh,
- detectGhAccounts,
- ensurePiBridge,
- getNativeTomlMcpEditor,
- loadConfig,
- makeLazyProbeTokenStore,
- probeOwnManagedEditorMcpEntry,
- probePiBridgeState,
-} from '@inkeep/open-knowledge';
-import { resolveServerRuntimeConfig, type ServerRuntimeConfig } from '@inkeep/open-knowledge-core';
-import {
- type BootedServer,
- type BootServerOptions,
- type Config,
- ConfigSchema,
- ensureProjectGit,
- initContent,
- makeLazyEmbeddingsKeyStore,
- type ServerExitReason,
+import type { ServerRuntimeConfig } from '@inkeep/open-knowledge-core';
+import type {
+ BootedServer,
+ BootServerOptions,
+ Config,
+ ServerExitReason,
} from '@inkeep/open-knowledge-server';
import { type KeyringSmokeResult, runKeyringSmoke } from './keyring-smoke.ts';
@@ -89,12 +75,18 @@ export type UtilityOutgoingMessage =
| UtilityDegradedMessage
| UtilityDebugKeyringSmokeResultMessage;
+type UtilityBootedServer = Pick<BootedServer, 'port' | 'destroy' | 'degraded'>;
+
+interface UtilityServerModule {
+ bootServer: (opts: BootServerOptions) => Promise<UtilityBootedServer>;
+}
+
export interface SetupUtilityDeps {
parentPort: {
on(event: 'message', handler: (event: { data: unknown }) => void): void;
postMessage(value: UtilityOutgoingMessage): void;
} | null;
- importServer: () => Promise<typeof import('@inkeep/open-knowledge-server')>;
+ importServer: () => Promise<UtilityServerModule>;
exit: (code: number) => void;
parentPid: number;
killProbe: (pid: number, signal: number | string) => void;
@@ -136,7 +128,7 @@ export interface UtilityHandle {
}
export function setupUtility(deps: SetupUtilityDeps): UtilityHandle {
- let booted: BootedServer | null = null;
+ let booted: UtilityBootedServer | null = null;
let parentPollHandle: { unref?: () => void; clear: () => void } | null = null;
let shuttingDown = false;
let resolveReady!: (msg: UtilityReadyMessage) => void;
@@ -193,7 +185,21 @@ export function setupUtility(deps: SetupUtilityDeps): UtilityHandle {
async function handleInit(msg: UtilityInitMessage) {
try {
- const server = await deps.importServer();
+ const [server, cli, serverNamespace] = await Promise.all([
+ deps.importServer(),
+ import('@inkeep/open-knowledge'),
+ import('@inkeep/open-knowledge-server'),
+ ]);
+ const {
+ detectGh,
+ detectGhAccounts,
+ ensurePiBridge,
+ getNativeTomlMcpEditor,
+ makeLazyProbeTokenStore,
+ probeOwnManagedEditorMcpEntry,
+ probePiBridgeState,
+ } = cli;
+ const { makeLazyEmbeddingsKeyStore } = serverNamespace;
const projectDir = msg.opts.projectDir ?? msg.opts.contentDir;
const prepare = deps.prepareBootEnvironment ?? defaultPrepareBootEnvironment;
const prepared = await prepare(msg.opts);
@@ -265,6 +271,10 @@ export function setupUtility(deps: SetupUtilityDeps): UtilityHandle {
});
}
} catch (err) {
+ console.warn('[utility] init failed', {
+ err: (err as Error).message,
+ stack: (err as Error).stack,
+ });
const errMsg: UtilityErrorMessage = {
type: 'error',
message: (err as Error).message,
@@ -371,11 +381,16 @@ function isAddressInUse(err: unknown): boolean {
);
}
-export function resolveDesktopServerRuntime(projectDir: string): {
+export async function resolveDesktopServerRuntime(projectDir: string): Promise<{
config: Config;
configValid: boolean;
serverRuntime: ServerRuntimeConfig;
-} {
+}> {
+ const [{ loadConfig }, { resolveServerRuntimeConfig }, { ConfigSchema }] = await Promise.all([
+ import('@inkeep/open-knowledge'),
+ import('@inkeep/open-knowledge-core'),
+ import('@inkeep/open-knowledge-server'),
+ ]);
let config: Config;
let configValid: boolean;
try {
@@ -405,6 +420,7 @@ async function defaultPrepareBootEnvironment(
ipcOpts: UtilityInitMessage['opts'],
): Promise<PreparedBootEnvironment> {
const projectDir = ipcOpts.projectDir ?? ipcOpts.contentDir;
+ const { ensureProjectGit, initContent } = await import('@inkeep/open-knowledge-server');
const degradedHints: string[] = [];
if (ipcOpts.didEnsureGit !== true) {
@@ -416,7 +432,7 @@ async function defaultPrepareBootEnvironment(
initContent(projectDir);
- const { config, configValid, serverRuntime } = resolveDesktopServerRuntime(projectDir);
+ const { config, configValid, serverRuntime } = await resolveDesktopServerRuntime(projectDir);
const contentDir = resolveContentDir(projectDir, config, ipcOpts.contentDir);
const rawContentDir = config.content.dir;