Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

52.6 KB
Raw Blame
import { execFileSync } from 'node:child_process';
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { createRequire } from 'node:module';
import { tmpdir } from 'node:os';
import { resolve } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
import { resolveServerRuntimeConfig } from '@inkeep/open-knowledge-core';
import {
  ConfigSchema,
  type ProcessStart,
  readProcessStart,
  registerNativeProcessStartReader,
} from '@inkeep/open-knowledge-server';
import { beforeEach, describe, expect, type Mock, test, vi } from 'vitest';
import { configureTestGitRepository } from '../../../../test-support/configure-git-fixture.test-helper.ts';
import { UTILITY_INIT_PHASES } from '../../src/shared/boot-narration.ts';
import type { KeyringSmokeResult } from '../../src/utility/keyring-smoke.ts';
import {
  type PreparedBootEnvironment,
  resolveContentDir,
  type SetupUtilityDeps,
  setupUtility,
  type UtilityOutgoingMessage,
} from '../../src/utility/server-entry.ts';

type UtilityParentPort = NonNullable<SetupUtilityDeps['parentPort']>;

interface MockParentPort {
  on: Mock<UtilityParentPort['on']>;
  postMessage: Mock<UtilityParentPort['postMessage']>;
  fire: (msg: unknown) => void;
}

function mockParentPort(): MockParentPort {
  let handler: ((event: { data: unknown }) => void) | null = null;
  const on = vi.fn<UtilityParentPort['on']>((_event, h) => {
    handler = h;
  });
  return {
    on,
    postMessage: vi.fn<UtilityParentPort['postMessage']>(() => {}),
    fire: (msg: unknown) => handler?.({ data: msg }),
  };
}

interface MockEnv {
  parentPort: MockParentPort;
  exit: Mock<SetupUtilityDeps['exit']>;
  killProbe: Mock<SetupUtilityDeps['killProbe']>;
  signalHandlers: Map<string, () => void>;
  intervals: Array<{ cb: () => void; ms: number }>;
  intervalCancel: Mock<() => void>;
}

function buildEnv(): MockEnv {
  const env: MockEnv = {
    parentPort: mockParentPort(),
    exit: vi.fn(() => {}),
    killProbe: vi.fn(() => {}),
    signalHandlers: new Map(),
    intervals: [],
    intervalCancel: vi.fn(() => {}),
  };
  return env;
}

function makeFakePrepared(overrides?: Partial<PreparedBootEnvironment>): PreparedBootEnvironment {
  const config = overrides?.config ?? ConfigSchema.parse({});
  return {
    config,
    contentDir: '/fake/content',
    contentRoot: undefined,
    configValid: true,
    serverRuntime: resolveServerRuntimeConfig(config),
    ...overrides,
  };
}

function fakePrepare(returnValue?: PreparedBootEnvironment) {
  return vi.fn(() => Promise.resolve(returnValue ?? makeFakePrepared()));
}

describe('setupUtility (IPC handshake + lifecycle)', () => {
  let env: MockEnv;

  beforeEach(() => {
    env = buildEnv();
  });

  test('on init message: imports server, calls bootServer with M1 opt-outs, posts ready', async () => {
    const fakeBooted = {
      port: 51234,
      destroy: vi.fn(() => Promise.resolve()),
      degraded: [] as readonly string[],
    };
    const bootServer = vi.fn(() => Promise.resolve(fakeBooted));
    const importServer = vi.fn(() =>
      Promise.resolve({ bootServer } as unknown as typeof import('@inkeep/open-knowledge-server')),
    );
    const prepared = makeFakePrepared({ contentDir: '/fake/test-project', contentRoot: undefined });

    const handle = setupUtility({
      parentPort: env.parentPort,
      importServer,
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
      prepareBootEnvironment: fakePrepare(prepared),
    });

    env.parentPort.fire({
      type: 'init',
      opts: {
        contentDir: '/tmp/test-project',
        projectDir: '/tmp/test-project',
        port: 0,
        host: 'localhost',
      },
    });

    const ready = await handle.readyPromise;
    expect(ready.type).toBe('ready');
    expect(ready.port).toBe(51234);
    expect(ready.apiOrigin).toBe('http://localhost:51234');

    const callArgs = bootServer.mock.calls[0]?.[0] as Record<string, unknown> | undefined;
    expect(callArgs?.idleShutdownMs).toBe(null);
    expect(callArgs?.skipAutoInit).toBe(true);
    expect(callArgs?.autoInitFn).toBeUndefined();
    expect(callArgs?.contentDir).toBe('/fake/test-project');
    expect(callArgs?.config).toBe(prepared.config);
    expect(callArgs?.serverRuntime).toBe(prepared.serverRuntime);
    expect(callArgs?.bind).toBe(prepared.serverRuntime.bind);

    expect(env.parentPort.postMessage).toHaveBeenCalledWith({
      type: 'ready',
      port: 51234,
      apiOrigin: 'http://localhost:51234',
    });
  });

  test('on init failure: posts error and exits non-zero', async () => {
    const importServer = vi.fn(() => Promise.reject(new Error('boot failed')));
    const handle = setupUtility({
      parentPort: env.parentPort,
      importServer,
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
    });

    env.parentPort.fire({
      type: 'init',
      opts: { contentDir: '/tmp/x', projectDir: '/tmp/x', port: 0, host: 'localhost' },
    });

    await expect(handle.readyPromise).rejects.toThrow('boot failed');
    expect(env.exit).toHaveBeenCalledWith(1);
  });

  test('parent-death poll: triggers shutdown on EPERM/ESRCH', async () => {
    const fakeBooted = {
      port: 51234,
      destroy: vi.fn(() => Promise.resolve()),
      degraded: [] as readonly string[],
    };
    const bootServer = vi.fn(() => Promise.resolve(fakeBooted));

    const handle = setupUtility({
      parentPort: env.parentPort,
      importServer: () =>
        Promise.resolve({
          bootServer,
        } as unknown as typeof import('@inkeep/open-knowledge-server')),
      exit: env.exit,
      parentPid: 99999,
      killProbe: () => {
        const err = new Error('No such process') as NodeJS.ErrnoException;
        err.code = 'ESRCH';
        throw err;
      },
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
      parentPollMs: 100,
      prepareBootEnvironment: fakePrepare(),
    });

    expect(env.intervals.length).toBeGreaterThan(0);
    const pollCb = env.intervals[0]?.cb;
    expect(pollCb).toBeDefined();
    pollCb?.();

    await wait(10);
    expect(env.exit).toHaveBeenCalledWith(0);
    void handle;
  });

  test('shutdown IPC: drains booted server then exits 0', async () => {
    const destroy = vi.fn(() => Promise.resolve());
    const fakeBooted = { port: 51234, destroy, degraded: [] as readonly string[] };
    const bootServer = vi.fn(() => Promise.resolve(fakeBooted));

    const handle = setupUtility({
      parentPort: env.parentPort,
      importServer: () =>
        Promise.resolve({
          bootServer,
        } as unknown as typeof import('@inkeep/open-knowledge-server')),
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
      prepareBootEnvironment: fakePrepare(),
    });

    env.parentPort.fire({
      type: 'init',
      opts: { contentDir: '/tmp/x', projectDir: '/tmp/x', port: 0, host: 'localhost' },
    });
    await handle.readyPromise;

    env.parentPort.fire({ type: 'shutdown' });
    await wait(10);

    expect(destroy).toHaveBeenCalledTimes(1);
    expect(env.exit).toHaveBeenCalledWith(0);
    expect(env.intervalCancel).toHaveBeenCalled();
  });

  test('SIGTERM handler triggers same shutdown path as IPC', async () => {
    const destroy = vi.fn(() => Promise.resolve());
    const fakeBooted = { port: 51234, destroy, degraded: [] as readonly string[] };
    const bootServer = vi.fn(() => Promise.resolve(fakeBooted));

    const handle = setupUtility({
      parentPort: env.parentPort,
      importServer: () =>
        Promise.resolve({
          bootServer,
        } as unknown as typeof import('@inkeep/open-knowledge-server')),
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
      prepareBootEnvironment: fakePrepare(),
    });

    env.parentPort.fire({
      type: 'init',
      opts: { contentDir: '/tmp/x', projectDir: '/tmp/x', port: 0, host: 'localhost' },
    });
    await handle.readyPromise;

    const sigtermHandler = env.signalHandlers.get('SIGTERM');
    expect(sigtermHandler).toBeDefined();
    sigtermHandler?.();
    await wait(10);

    expect(destroy).toHaveBeenCalledTimes(1);
    expect(env.exit).toHaveBeenCalledWith(0);
  });

  test('shutdown is idempotent — multiple calls drain once', async () => {
    const destroy = vi.fn(() => Promise.resolve());
    const fakeBooted = { port: 51234, destroy, degraded: [] as readonly string[] };
    const bootServer = vi.fn(() => Promise.resolve(fakeBooted));

    const handle = setupUtility({
      parentPort: env.parentPort,
      importServer: () =>
        Promise.resolve({
          bootServer,
        } as unknown as typeof import('@inkeep/open-knowledge-server')),
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
      prepareBootEnvironment: fakePrepare(),
    });

    env.parentPort.fire({
      type: 'init',
      opts: { contentDir: '/tmp/x', projectDir: '/tmp/x', port: 0, host: 'localhost' },
    });
    await handle.readyPromise;

    await handle.shutdown('test-1');
    await handle.shutdown('test-2');
    expect(destroy).toHaveBeenCalledTimes(1);
  });

  test('boot auto-smoke: OK_DEBUG_KEYRING_SMOKE=1 + OUT path writes JSON atomically', async () => {
    const smokeResult: KeyringSmokeResult = {
      ok: true,
      backend: 'keyring',
      durationMs: 12,
      timestamp: '2026-04-21T00:00:00.000Z',
    };
    const runSmoke = vi.fn(() => Promise.resolve(smokeResult));
    const writeSmokeResult = vi.fn(() => Promise.resolve());

    setupUtility({
      parentPort: env.parentPort,
      importServer: () =>
        Promise.resolve({} as unknown as typeof import('@inkeep/open-knowledge-server')),
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
      runSmoke,
      env: {
        OK_DEBUG_KEYRING_SMOKE: '1',
        OK_DEBUG_KEYRING_SMOKE_OUT: '/tmp/smoke-out.json',
      },
      writeSmokeResult,
    });

    await wait(5);

    expect(runSmoke).toHaveBeenCalledTimes(1);
    expect(writeSmokeResult).toHaveBeenCalledTimes(1);
    const [writtenPath, writtenContents] = writeSmokeResult.mock.calls[0] as [string, string];
    expect(writtenPath).toBe('/tmp/smoke-out.json');
    const parsed = JSON.parse(writtenContents) as KeyringSmokeResult;
    expect(parsed).toEqual(smokeResult);
    expect(writtenContents.endsWith('\n')).toBe(true);
    expect(env.exit).not.toHaveBeenCalled();
  });

  test('boot auto-smoke + EXIT=1: calls exit(0) after write, does NOT register listener', async () => {
    const smokeResult: KeyringSmokeResult = {
      ok: true,
      backend: 'keyring',
      durationMs: 5,
      timestamp: '2026-04-21T00:00:00.000Z',
    };
    const runSmoke = vi.fn(() => Promise.resolve(smokeResult));
    const writeSmokeResult = vi.fn(() => Promise.resolve());

    setupUtility({
      parentPort: env.parentPort,
      importServer: () =>
        Promise.resolve({} as unknown as typeof import('@inkeep/open-knowledge-server')),
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
      runSmoke,
      env: {
        OK_DEBUG_KEYRING_SMOKE: '1',
        OK_DEBUG_KEYRING_SMOKE_OUT: '/tmp/smoke-exit.json',
        OK_DEBUG_KEYRING_SMOKE_EXIT: '1',
      },
      writeSmokeResult,
    });

    await wait(5);

    expect(runSmoke).toHaveBeenCalledTimes(1);
    expect(writeSmokeResult).toHaveBeenCalledTimes(1);
    expect(env.exit).toHaveBeenCalledWith(0);
    expect(env.parentPort.on).not.toHaveBeenCalled();
  });

  test('boot auto-smoke: OK_DEBUG_KEYRING_SMOKE=1 without OUT path still posts IPC result', async () => {
    const smokeResult: KeyringSmokeResult = {
      ok: true,
      backend: 'keyring',
      durationMs: 8,
      timestamp: '2026-04-21T00:00:00.000Z',
    };
    const runSmoke = vi.fn(() => Promise.resolve(smokeResult));
    const writeSmokeResult = vi.fn(() => Promise.resolve());

    setupUtility({
      parentPort: env.parentPort,
      importServer: () =>
        Promise.resolve({} as unknown as typeof import('@inkeep/open-knowledge-server')),
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
      runSmoke,
      env: { OK_DEBUG_KEYRING_SMOKE: '1' },
      writeSmokeResult,
    });

    await wait(5);

    expect(runSmoke).toHaveBeenCalledTimes(1);
    expect(writeSmokeResult).not.toHaveBeenCalled();
    expect(env.parentPort.postMessage).toHaveBeenCalledWith({
      type: 'debug-keyring-smoke-result',
      correlationId: 'auto-boot',
      result: smokeResult,
    });
    expect(env.parentPort.on).toHaveBeenCalled();
  });

  test('boot auto-smoke: env unset → no smoke runs, listener registered immediately', async () => {
    const runSmoke = vi.fn(() =>
      Promise.resolve({ ok: true, timestamp: 'x' } as KeyringSmokeResult),
    );

    setupUtility({
      parentPort: env.parentPort,
      importServer: () =>
        Promise.resolve({} as unknown as typeof import('@inkeep/open-knowledge-server')),
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
      runSmoke,
      env: {},
    });

    await wait(5);

    expect(runSmoke).not.toHaveBeenCalled();
    expect(env.parentPort.on).toHaveBeenCalled();
  });

  test('boot auto-smoke: write failure logs + continues (does NOT exit or hang)', async () => {
    const smokeResult: KeyringSmokeResult = {
      ok: true,
      backend: 'keyring',
      durationMs: 3,
      timestamp: '2026-04-21T00:00:00.000Z',
    };
    const runSmoke = vi.fn(() => Promise.resolve(smokeResult));
    const writeSmokeResult = vi.fn(() => Promise.reject(new Error('EACCES')));

    setupUtility({
      parentPort: env.parentPort,
      importServer: () =>
        Promise.resolve({} as unknown as typeof import('@inkeep/open-knowledge-server')),
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
      runSmoke,
      env: {
        OK_DEBUG_KEYRING_SMOKE: '1',
        OK_DEBUG_KEYRING_SMOKE_OUT: '/tmp/unwritable/smoke.json',
      },
      writeSmokeResult,
    });

    await wait(5);

    expect(runSmoke).toHaveBeenCalledTimes(1);
    expect(writeSmokeResult).toHaveBeenCalledTimes(1);
    expect(env.exit).not.toHaveBeenCalled();
    expect(env.parentPort.on).toHaveBeenCalled();
  });

  test('debug-keyring-smoke IPC: invokes injected runSmoke and echoes correlationId', async () => {
    const smokeResult: KeyringSmokeResult = {
      ok: true,
      backend: 'keyring',
      durationMs: 7,
      timestamp: '2026-04-21T00:00:00.000Z',
    };
    const runSmoke = vi.fn(() => Promise.resolve(smokeResult));

    setupUtility({
      parentPort: env.parentPort,
      importServer: () =>
        Promise.resolve({
          bootServer: vi.fn(() => Promise.resolve({})),
        } as unknown as typeof import('@inkeep/open-knowledge-server')),
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
      runSmoke,
    });

    env.parentPort.fire({ type: 'debug-keyring-smoke', correlationId: 'abc-123' });
    await wait(5);

    expect(runSmoke).toHaveBeenCalledTimes(1);
    expect(env.parentPort.postMessage).toHaveBeenCalledWith({
      type: 'debug-keyring-smoke-result',
      correlationId: 'abc-123',
      result: smokeResult,
    });
  });

  test('degraded subsystems are reported via separate IPC after ready', async () => {
    const fakeBooted = {
      port: 51234,
      destroy: vi.fn(() => Promise.resolve()),
      degraded: ['shadow-repo'] as readonly string[],
    };
    const bootServer = vi.fn(() => Promise.resolve(fakeBooted));

    const handle = setupUtility({
      parentPort: env.parentPort,
      importServer: () =>
        Promise.resolve({
          bootServer,
        } as unknown as typeof import('@inkeep/open-knowledge-server')),
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
      prepareBootEnvironment: fakePrepare(),
    });

    env.parentPort.fire({
      type: 'init',
      opts: { contentDir: '/tmp/x', projectDir: '/tmp/x', port: 0, host: 'localhost' },
    });
    await handle.readyPromise;

    expect(env.parentPort.postMessage).toHaveBeenCalledWith({
      type: 'degraded',
      subsystems: ['shadow-repo'],
    });
  });
});

describe('handleInit boot prelude (FR-16/17/18/19/22/24)', () => {
  let env: MockEnv;

  beforeEach(() => {
    env = buildEnv();
  });

  test('loaded config.content.dir overrides IPC contentDir hint', async () => {
    const config = ConfigSchema.parse({ content: { dir: 'docs' } });
    const prepared = makeFakePrepared({
      config,
      contentDir: '/projects/myrepo/docs',
      contentRoot: 'docs',
    });
    const fakeBooted = {
      port: 4242,
      destroy: vi.fn(() => Promise.resolve()),
      degraded: [] as readonly string[],
    };
    const bootServer = vi.fn(() => Promise.resolve(fakeBooted));

    const handle = setupUtility({
      parentPort: env.parentPort,
      importServer: () =>
        Promise.resolve({
          bootServer,
        } as unknown as typeof import('@inkeep/open-knowledge-server')),
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
      prepareBootEnvironment: fakePrepare(prepared),
    });

    env.parentPort.fire({
      type: 'init',
      opts: {
        contentDir: '/projects/myrepo',
        projectDir: '/projects/myrepo',
        port: 0,
        host: 'localhost',
      },
    });
    await handle.readyPromise;

    const callArgs = bootServer.mock.calls[0]?.[0] as Record<string, unknown> | undefined;
    expect(callArgs?.contentDir).toBe('/projects/myrepo/docs');
    expect(callArgs?.contentRoot).toBe('docs');
    expect(callArgs?.config).toBe(config);
  });

  test('IPC didEnsureGit + consentVersion are forwarded to the prepare hook', async () => {
    const prepare = fakePrepare();
    const fakeBooted = {
      port: 4242,
      destroy: vi.fn(() => Promise.resolve()),
      degraded: [] as readonly string[],
    };
    const bootServer = vi.fn(() => Promise.resolve(fakeBooted));

    const handle = setupUtility({
      parentPort: env.parentPort,
      importServer: () =>
        Promise.resolve({
          bootServer,
        } as unknown as typeof import('@inkeep/open-knowledge-server')),
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
      prepareBootEnvironment: prepare,
    });

    env.parentPort.fire({
      type: 'init',
      opts: {
        contentDir: '/projects/myrepo',
        projectDir: '/projects/myrepo',
        port: 0,
        host: 'localhost',
        didEnsureGit: true,
        consentVersion: 1,
      },
    });
    await handle.readyPromise;

    const ipcArgs = prepare.mock.calls[0]?.[0] as Record<string, unknown> | undefined;
    expect(ipcArgs?.didEnsureGit).toBe(true);
    expect(ipcArgs?.consentVersion).toBe(1);
    expect(ipcArgs?.projectDir).toBe('/projects/myrepo');
  });

  test('lets the server read Windows process starts before it prepares the boot environment', async () => {
    const builtCliEntry = createRequire(import.meta.url).resolve('@inkeep/open-knowledge');
    const nativeConfig: { readProcessStart: (pid: number) => number | null } =
      createRequire(builtCliEntry)('./native/index.js');
    const nativeRead = vi
      .spyOn(nativeConfig, 'readProcessStart')
      .mockReturnValue(1_789_000_000_456);
    registerNativeProcessStartReader(() => null)();
    await import('@inkeep/open-knowledge');
    const readingBeforeInit = readProcessStart(4242, { platform: 'win32' });
    let readingWhilePreparing: ProcessStart | null = null;
    const prepare = vi.fn(() => {
      readingWhilePreparing = readProcessStart(4242, { platform: 'win32' });
      return Promise.resolve(makeFakePrepared());
    });
    const bootServer = vi.fn(() =>
      Promise.resolve({
        port: 4242,
        destroy: vi.fn(() => Promise.resolve()),
        degraded: [] as readonly string[],
      }),
    );

    try {
      const handle = setupUtility({
        parentPort: env.parentPort,
        importServer: () =>
          Promise.resolve({
            bootServer,
          } as unknown as typeof import('@inkeep/open-knowledge-server')),
        exit: env.exit,
        parentPid: 99999,
        killProbe: env.killProbe,
        onSignal: (sig, h) => env.signalHandlers.set(sig, h),
        setInterval: (cb, ms) => {
          env.intervals.push({ cb, ms });
          return { unref: vi.fn(() => {}), clear: env.intervalCancel };
        },
        prepareBootEnvironment: prepare,
      });

      env.parentPort.fire({
        type: 'init',
        opts: {
          contentDir: '/projects/myrepo',
          projectDir: '/projects/myrepo',
          port: 0,
          host: 'localhost',
        },
      });
      await handle.readyPromise;

      expect(prepare).toHaveBeenCalledTimes(1);
      expect(readingBeforeInit).toBeNull();
      expect(readingWhilePreparing).toEqual({ startedAtMs: 1_789_000_000_456, clock: 'creation' });
      expect(nativeRead).toHaveBeenCalledWith(4242);
    } finally {
      nativeRead.mockRestore();
      registerNativeProcessStartReader(() => null)();
    }
  });

  test('OK_DEBUG_DESKTOP_BOOT_TRACE=1 logs the resolved config trace', async () => {
    const fakeBooted = {
      port: 4242,
      destroy: vi.fn(() => Promise.resolve()),
      degraded: [] as readonly string[],
    };
    const bootServer = vi.fn(() => Promise.resolve(fakeBooted));
    const warnSpy = vi.fn(() => {});
    const originalWarn = console.warn;
    console.warn = warnSpy;
    try {
      const handle = setupUtility({
        parentPort: env.parentPort,
        importServer: () =>
          Promise.resolve({
            bootServer,
          } as unknown as typeof import('@inkeep/open-knowledge-server')),
        exit: env.exit,
        parentPid: 99999,
        killProbe: env.killProbe,
        onSignal: (sig, h) => env.signalHandlers.set(sig, h),
        setInterval: (cb, ms) => {
          env.intervals.push({ cb, ms });
          return { unref: vi.fn(() => {}), clear: env.intervalCancel };
        },
        prepareBootEnvironment: fakePrepare(
          makeFakePrepared({
            contentDir: '/projects/myrepo/docs',
            contentRoot: 'docs',
            configValid: true,
          }),
        ),
        env: { OK_DEBUG_DESKTOP_BOOT_TRACE: '1' },
      });

      env.parentPort.fire({
        type: 'init',
        opts: {
          contentDir: '/projects/myrepo',
          projectDir: '/projects/myrepo',
          port: 0,
          host: 'localhost',
        },
      });
      await handle.readyPromise;

      const traceCall = warnSpy.mock.calls.find((args) =>
        String(args[0] ?? '').startsWith('[desktop-boot-trace]'),
      );
      expect(traceCall).toBeDefined();
      const traceLine = String(traceCall?.[0] ?? '');
      expect(traceLine).toContain('projectDir=/projects/myrepo');
      expect(traceLine).toContain('contentRoot="docs"');
      expect(traceLine).toContain('resolvedContentDir=/projects/myrepo/docs');
      expect(traceLine).toContain('configValid=true');
    } finally {
      console.warn = originalWarn;
    }
  });

  test('bootServer always receives a full ConfigSchema-parsed object (FR-19a)', async () => {
    const config = ConfigSchema.parse({});
    const prepared = makeFakePrepared({ config, configValid: false });
    const fakeBooted = {
      port: 4242,
      destroy: vi.fn(() => Promise.resolve()),
      degraded: [] as readonly string[],
    };
    const bootServer = vi.fn(() => Promise.resolve(fakeBooted));

    const handle = setupUtility({
      parentPort: env.parentPort,
      importServer: () =>
        Promise.resolve({
          bootServer,
        } as unknown as typeof import('@inkeep/open-knowledge-server')),
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
      prepareBootEnvironment: fakePrepare(prepared),
    });

    env.parentPort.fire({
      type: 'init',
      opts: {
        contentDir: '/projects/myrepo',
        projectDir: '/projects/myrepo',
        port: 0,
        host: 'localhost',
      },
    });
    await handle.readyPromise;

    const callArgs = bootServer.mock.calls[0]?.[0] as Record<string, unknown> | undefined;
    expect(callArgs?.config).toBeDefined();
    const passedConfig = callArgs?.config as { content?: { dir?: unknown } } | undefined;
    expect(passedConfig?.content?.dir).toBeDefined();
  });
});

describe('resolveContentDir (FR-17 unit)', () => {
  test('empty config.content.dir falls back to ipcFallback', () => {
    const config = ConfigSchema.parse({ content: { dir: '' } });
    expect(resolveContentDir('/projects/myrepo', config, '/ipc/picked')).toBe('/ipc/picked');
  });

  test('"." falls back to ipcFallback', () => {
    const config = ConfigSchema.parse({ content: { dir: '.' } });
    expect(resolveContentDir('/projects/myrepo', config, '/ipc/picked')).toBe('/ipc/picked');
  });

  test('non-trivial relative content.dir wins over ipcFallback', () => {
    const config = ConfigSchema.parse({ content: { dir: 'docs' } });
    expect(resolveContentDir('/projects/myrepo', config, '/ipc/picked')).toBe(
      '/projects/myrepo/docs',
    );
  });

  test('absolute content.dir inside projectDir is honored', () => {
    const config = ConfigSchema.parse({ content: { dir: '/projects/myrepo/docs' } });
    expect(resolveContentDir('/projects/myrepo', config, '/ipc/picked')).toBe(
      '/projects/myrepo/docs',
    );
  });

  test('".." escape falls back to ipcFallback (defense-in-depth)', () => {
    const warnSpy = vi.fn(() => {});
    const originalWarn = console.warn;
    console.warn = warnSpy;
    try {
      const config = ConfigSchema.parse({ content: { dir: '../escape' } });
      expect(resolveContentDir('/projects/myrepo', config, '/ipc/picked')).toBe('/ipc/picked');
      const escapeWarning = warnSpy.mock.calls.find((args) =>
        String(args[0] ?? '').includes('content.dir='),
      );
      expect(escapeWarning).toBeDefined();
    } finally {
      console.warn = originalWarn;
    }
  });

  test('absolute content.dir outside projectDir falls back to ipcFallback', () => {
    const warnSpy = vi.fn(() => {});
    const originalWarn = console.warn;
    console.warn = warnSpy;
    try {
      const config = ConfigSchema.parse({ content: { dir: '/elsewhere/secrets' } });
      expect(resolveContentDir('/projects/myrepo', config, '/ipc/picked')).toBe('/ipc/picked');
    } finally {
      console.warn = originalWarn;
    }
  });

  test('undefined ipcFallback defaults to projectDir for the empty/. case', () => {
    const config = ConfigSchema.parse({});
    expect(resolveContentDir('/projects/myrepo', config, undefined)).toBe('/projects/myrepo');
  });
});

describe('handleInit defaultPrepareBootEnvironment (integration)', () => {
  let env: MockEnv;
  let tmpRoot: string;

  beforeEach(() => {
    env = buildEnv();
    tmpRoot = mkdtempSync(resolve(tmpdir(), 'ok-utility-prelude-'));
  });

  test('loads real .ok/config.yml + resolves content.dir via the production prelude', async () => {
    mkdirSync(resolve(tmpRoot, '.git'), { recursive: true });
    writeFileSync(resolve(tmpRoot, '.git/HEAD'), 'ref: refs/heads/main\n', 'utf-8');
    mkdirSync(resolve(tmpRoot, '.ok'), { recursive: true });
    writeFileSync(
      resolve(tmpRoot, '.ok/config.yml'),
      'version: 1\ncontent:\n  dir: docs\n',
      'utf-8',
    );
    mkdirSync(resolve(tmpRoot, 'docs'), { recursive: true });

    const fakeBooted = {
      port: 4242,
      destroy: vi.fn(() => Promise.resolve()),
      degraded: [] as readonly string[],
    };
    const bootServer = vi.fn(() => Promise.resolve(fakeBooted));

    const handle = setupUtility({
      parentPort: env.parentPort,
      importServer: () =>
        Promise.resolve({
          bootServer,
        } as unknown as typeof import('@inkeep/open-knowledge-server')),
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
    });

    env.parentPort.fire({
      type: 'init',
      opts: {
        contentDir: tmpRoot,
        projectDir: tmpRoot,
        port: 0,
        host: 'localhost',
        didEnsureGit: true,
      },
    });
    await handle.readyPromise;

    const callArgs = bootServer.mock.calls[0]?.[0] as Record<string, unknown> | undefined;
    expect(callArgs?.contentDir).toBe(resolve(tmpRoot, 'docs'));
    expect(callArgs?.contentRoot).toBe('docs');
    const passedConfig = callArgs?.config as { content?: { dir?: unknown } } | undefined;
    expect(passedConfig?.content?.dir).toBe('docs');

    rmSync(tmpRoot, { recursive: true, force: true });
  });

  test('didEnsureGit=false runs ensureProjectGit which scaffolds a real .git/', async () => {
    const fakeBooted = {
      port: 4242,
      destroy: vi.fn(() => Promise.resolve()),
      degraded: [] as readonly string[],
    };
    const bootServer = vi.fn(() => Promise.resolve(fakeBooted));

    const handle = setupUtility({
      parentPort: env.parentPort,
      importServer: () =>
        Promise.resolve({
          bootServer,
        } as unknown as typeof import('@inkeep/open-knowledge-server')),
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
    });

    env.parentPort.fire({
      type: 'init',
      opts: {
        contentDir: tmpRoot,
        projectDir: tmpRoot,
        port: 0,
        host: 'localhost',
      },
    });
    await handle.readyPromise;
    configureTestGitRepository(tmpRoot);

    const headPath = resolve(tmpRoot, '.git/HEAD');
    const configPath = resolve(tmpRoot, '.ok/config.yml');
    const headStat = execFileSync('test', ['-f', headPath], { encoding: 'utf-8' });
    expect(headStat).toBe('');
    const configStat = execFileSync('test', ['-f', configPath], { encoding: 'utf-8' });
    expect(configStat).toBe('');

    rmSync(tmpRoot, { recursive: true, force: true });
  });

  test('invalid YAML config falls back to schema defaults and logs warning', async () => {
    mkdirSync(resolve(tmpRoot, '.git'), { recursive: true });
    writeFileSync(resolve(tmpRoot, '.git/HEAD'), 'ref: refs/heads/main\n', 'utf-8');
    mkdirSync(resolve(tmpRoot, '.ok'), { recursive: true });
    writeFileSync(resolve(tmpRoot, '.ok/config.yml'), 'version: 1\ncontent: {\n', 'utf-8');

    const fakeBooted = {
      port: 4242,
      destroy: vi.fn(() => Promise.resolve()),
      degraded: [] as readonly string[],
    };
    const bootServer = vi.fn(() => Promise.resolve(fakeBooted));

    const warnSpy = vi.fn(() => {});
    const originalWarn = console.warn;
    console.warn = warnSpy;
    try {
      const handle = setupUtility({
        parentPort: env.parentPort,
        importServer: () =>
          Promise.resolve({
            bootServer,
          } as unknown as typeof import('@inkeep/open-knowledge-server')),
        exit: env.exit,
        parentPid: 99999,
        killProbe: env.killProbe,
        onSignal: (sig, h) => env.signalHandlers.set(sig, h),
        setInterval: (cb, ms) => {
          env.intervals.push({ cb, ms });
          return { unref: vi.fn(() => {}), clear: env.intervalCancel };
        },
      });

      env.parentPort.fire({
        type: 'init',
        opts: {
          contentDir: tmpRoot,
          projectDir: tmpRoot,
          port: 0,
          host: 'localhost',
          didEnsureGit: true,
        },
      });
      await handle.readyPromise;

      const fallbackWarn = warnSpy.mock.calls.find((args) =>
        String(args[0] ?? '').includes('[config] Failed to parse'),
      );
      expect(fallbackWarn).toBeDefined();

      expect(bootServer).toHaveBeenCalled();
      const callArgs = bootServer.mock.calls[0]?.[0] as Record<string, unknown> | undefined;
      const passedConfig = callArgs?.config as { content?: { dir?: unknown } } | undefined;
      expect(passedConfig?.content?.dir).toBe('.');
    } finally {
      console.warn = originalWarn;
    }

    rmSync(tmpRoot, { recursive: true, force: true });
  });

  test('initContent is idempotent on re-runs — does not clobber an existing config.yml', async () => {
    mkdirSync(resolve(tmpRoot, '.git'), { recursive: true });
    writeFileSync(resolve(tmpRoot, '.git/HEAD'), 'ref: refs/heads/main\n', 'utf-8');
    mkdirSync(resolve(tmpRoot, '.ok'), { recursive: true });
    const userCustomized = 'version: 1\ncontent:\n  dir: notes\n';
    writeFileSync(resolve(tmpRoot, '.ok/config.yml'), userCustomized, 'utf-8');
    mkdirSync(resolve(tmpRoot, 'notes'), { recursive: true });

    const fakeBooted = {
      port: 4242,
      destroy: vi.fn(() => Promise.resolve()),
      degraded: [] as readonly string[],
    };
    const bootServer = vi.fn(() => Promise.resolve(fakeBooted));

    const handle = setupUtility({
      parentPort: env.parentPort,
      importServer: () =>
        Promise.resolve({
          bootServer,
        } as unknown as typeof import('@inkeep/open-knowledge-server')),
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
    });

    env.parentPort.fire({
      type: 'init',
      opts: {
        contentDir: tmpRoot,
        projectDir: tmpRoot,
        port: 0,
        host: 'localhost',
        didEnsureGit: true,
      },
    });
    await handle.readyPromise;

    const { readFileSync } = await import('node:fs');
    const post = readFileSync(resolve(tmpRoot, '.ok/config.yml'), 'utf-8');
    expect(post).toBe(userCustomized);

    rmSync(tmpRoot, { recursive: true, force: true });
  });
});

const PLANNED_UTILITY_INIT_PHASES = [
  'init-received',
  'imports-resolved',
  'project-git-ensured',
  'boot-server-started',
];

const PHASES_WITHOUT_ENSURING_GIT = PLANNED_UTILITY_INIT_PHASES.filter(
  (phase) => phase !== 'project-git-ensured',
);

function postedToMain(env: MockEnv): UtilityOutgoingMessage[] {
  return env.parentPort.postMessage.mock.calls.map(([message]) => message);
}

function initPhasesPostedToMain(env: MockEnv): unknown[] {
  return postedToMain(env)
    .filter((message) => message.type === 'init-phase')
    .map((message) => message.phase);
}

function countersAtRead(read: number): {
  uptimeMs: number;
  cpuUserMs: number;
  cpuSystemMs: number;
} {
  return { uptimeMs: read * 3, cpuUserMs: read * 2, cpuSystemMs: read };
}

function isUsableCounter(counter: unknown): boolean {
  return typeof counter === 'number' && Number.isFinite(counter) && counter >= 0;
}

describe('setupUtility narrates its startup phases to main before it reports ready', () => {
  let env: MockEnv;

  beforeEach(() => {
    env = buildEnv();
  });

  test('marks receiving init, resolving its imports and starting the server, each with the counters read at that mark, then posts ready', async () => {
    const phasesPostedBefore: Record<string, unknown[]> = {};
    let counterReads = 0;
    const fakeBooted = {
      port: 51234,
      destroy: vi.fn(() => Promise.resolve()),
      degraded: [] as readonly string[],
    };
    const bootServer = vi.fn(() => {
      phasesPostedBefore.bootServer = initPhasesPostedToMain(env);
      return Promise.resolve(fakeBooted);
    });
    const plannedDeps = {
      readInitCounters: () => {
        counterReads += 1;
        return countersAtRead(counterReads);
      },
    };

    const handle = setupUtility({
      parentPort: env.parentPort,
      importServer: () => {
        phasesPostedBefore.importServer = initPhasesPostedToMain(env);
        return Promise.resolve({
          bootServer,
        } as unknown as typeof import('@inkeep/open-knowledge-server'));
      },
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
      prepareBootEnvironment: () => {
        phasesPostedBefore.prepare = initPhasesPostedToMain(env);
        return Promise.resolve(makeFakePrepared());
      },
      ...plannedDeps,
    });

    env.parentPort.fire({
      type: 'init',
      opts: { contentDir: '/tmp/x', projectDir: '/tmp/x', port: 0, host: 'localhost' },
    });
    await handle.readyPromise;

    expect(postedToMain(env)).toEqual([
      ...PHASES_WITHOUT_ENSURING_GIT.map((phase, index) => ({
        type: 'init-phase',
        phase,
        ...countersAtRead(index + 1),
      })),
      { type: 'ready', port: 51234, apiOrigin: 'http://localhost:51234' },
    ]);
    expect(phasesPostedBefore).toEqual({
      importServer: PHASES_WITHOUT_ENSURING_GIT.slice(0, 1),
      prepare: PHASES_WITHOUT_ENSURING_GIT.slice(0, 2),
      bootServer: PHASES_WITHOUT_ENSURING_GIT,
    });
  });

  test.each([
    { didEnsureGit: false, markedPhases: PLANNED_UTILITY_INIT_PHASES },
    { didEnsureGit: true, markedPhases: PHASES_WITHOUT_ENSURING_GIT },
  ])(
    'marks ensuring the project git only when it ensured it itself (didEnsureGit=$didEnsureGit), with counters it read itself',
    async ({ didEnsureGit, markedPhases }) => {
      expect(UTILITY_INIT_PHASES).toEqual(PLANNED_UTILITY_INIT_PHASES);
      const tmpRoot = mkdtempSync(resolve(tmpdir(), 'ok-utility-phase-marks-'));
      if (didEnsureGit) {
        mkdirSync(resolve(tmpRoot, '.git'), { recursive: true });
        writeFileSync(resolve(tmpRoot, '.git/HEAD'), 'ref: refs/heads/main\n', 'utf-8');
      }
      try {
        const fakeBooted = {
          port: 4242,
          destroy: vi.fn(() => Promise.resolve()),
          degraded: [] as readonly string[],
        };
        const bootServer = vi.fn(() => Promise.resolve(fakeBooted));
        const handle = setupUtility({
          parentPort: env.parentPort,
          importServer: () =>
            Promise.resolve({
              bootServer,
            } as unknown as typeof import('@inkeep/open-knowledge-server')),
          exit: env.exit,
          parentPid: 99999,
          killProbe: env.killProbe,
          onSignal: (sig, h) => env.signalHandlers.set(sig, h),
          setInterval: (cb, ms) => {
            env.intervals.push({ cb, ms });
            return { unref: vi.fn(() => {}), clear: env.intervalCancel };
          },
        });

        env.parentPort.fire({
          type: 'init',
          opts: {
            contentDir: tmpRoot,
            projectDir: tmpRoot,
            port: 0,
            host: 'localhost',
            didEnsureGit,
          },
        });
        await handle.readyPromise;
        if (!didEnsureGit) configureTestGitRepository(tmpRoot);

        const posted = postedToMain(env);
        const marks = posted.filter((message) => message.type === 'init-phase');
        expect(marks.map((mark) => mark.phase)).toEqual(markedPhases);
        expect(
          marks
            .flatMap((mark) => [mark.uptimeMs, mark.cpuUserMs, mark.cpuSystemMs])
            .filter((counter) => !isUsableCounter(counter)),
        ).toEqual([]);
        expect(posted.findIndex((message) => message.type === 'ready')).toBeGreaterThan(
          posted.findLastIndex((message) => message.type === 'init-phase'),
        );
      } finally {
        rmSync(tmpRoot, { recursive: true, force: true });
      }
    },
  );

  test('reports a failed start as an error after the phase marks it reached', async () => {
    const handle = setupUtility({
      parentPort: env.parentPort,
      importServer: vi.fn(() => Promise.reject(new Error('boot failed'))),
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
    });

    env.parentPort.fire({
      type: 'init',
      opts: { contentDir: '/tmp/x', projectDir: '/tmp/x', port: 0, host: 'localhost' },
    });

    await expect(handle.readyPromise).rejects.toThrow('boot failed');
    expect(
      postedToMain(env).map((message) =>
        message.type === 'init-phase' ? message.phase : message.type,
      ),
    ).toEqual([...PHASES_WITHOUT_ENSURING_GIT.slice(0, 1), 'error']);
    expect(env.exit).toHaveBeenCalledWith(1);
  });

  test('reads its default phase counters in milliseconds of its own uptime and CPU clocks', async () => {
    const tmpRoot = mkdtempSync(resolve(tmpdir(), 'ok-utility-phase-counters-'));
    mkdirSync(resolve(tmpRoot, '.git'), { recursive: true });
    writeFileSync(resolve(tmpRoot, '.git/HEAD'), 'ref: refs/heads/main\n', 'utf-8');
    try {
      const fakeBooted = {
        port: 4243,
        destroy: vi.fn(() => Promise.resolve()),
        degraded: [] as readonly string[],
      };
      const handle = setupUtility({
        parentPort: env.parentPort,
        importServer: () =>
          Promise.resolve({
            bootServer: vi.fn(() => Promise.resolve(fakeBooted)),
          } as unknown as typeof import('@inkeep/open-knowledge-server')),
        exit: env.exit,
        parentPid: 99999,
        killProbe: env.killProbe,
        onSignal: (sig, h) => env.signalHandlers.set(sig, h),
        setInterval: (cb, ms) => {
          env.intervals.push({ cb, ms });
          return { unref: vi.fn(() => {}), clear: env.intervalCancel };
        },
      });

      const beforeInit = ownClocksInMs(Math.floor);
      env.parentPort.fire({
        type: 'init',
        opts: {
          contentDir: tmpRoot,
          projectDir: tmpRoot,
          port: 0,
          host: 'localhost',
          didEnsureGit: true,
        },
      });
      await handle.readyPromise;
      const afterReady = ownClocksInMs(Math.ceil);

      const marks = postedToMain(env).filter((message) => message.type === 'init-phase');
      expect(marks.map((mark) => mark.phase)).toEqual(PHASES_WITHOUT_ENSURING_GIT);
      expect(
        marks.flatMap((mark) =>
          OWN_CLOCK_COUNTERS.filter((counter) => {
            const value = mark[counter];
            return !(
              typeof value === 'number' &&
              value >= beforeInit[counter] &&
              value <= afterReady[counter]
            );
          }).map((counter) => ({
            phase: mark.phase,
            counter,
            value: mark[counter],
            from: beforeInit[counter],
            to: afterReady[counter],
          })),
        ),
      ).toEqual([]);
    } finally {
      rmSync(tmpRoot, { recursive: true, force: true });
    }
  });
});

const OWN_CLOCK_COUNTERS = ['uptimeMs', 'cpuUserMs', 'cpuSystemMs'] as const;

function ownClocksInMs(
  round: (ms: number) => number,
): Record<(typeof OWN_CLOCK_COUNTERS)[number], number> {
  const cpu = process.cpuUsage();
  return {
    uptimeMs: round(process.uptime() * 1000),
    cpuUserMs: round(cpu.user / 1000),
    cpuSystemMs: round(cpu.system / 1000),
  };
}

function startUtilityWhoseBootPreparationWaits(env: MockEnv): {
  bootServer: Mock<
    () => Promise<{ port: number; destroy: () => Promise<void>; degraded: readonly string[] }>
  >;
  reachedBootPreparation: Promise<void>;
  finishBootPreparation: () => void;
} {
  const { promise: entered, resolve: enterBootPreparation } = Promise.withResolvers<void>();
  const { promise: finished, resolve: finishBootPreparation } = Promise.withResolvers<void>();
  const bootServer = vi.fn(() =>
    Promise.resolve({
      port: 51289,
      destroy: () => Promise.resolve(),
      degraded: [] as readonly string[],
    }),
  );
  const handle = setupUtility({
    parentPort: env.parentPort,
    importServer: () =>
      Promise.resolve({
        bootServer,
      } as unknown as typeof import('@inkeep/open-knowledge-server')),
    exit: env.exit,
    parentPid: 99999,
    killProbe: env.killProbe,
    onSignal: (sig, h) => env.signalHandlers.set(sig, h),
    setInterval: (cb, ms) => {
      env.intervals.push({ cb, ms });
      return { unref: vi.fn(() => {}), clear: env.intervalCancel };
    },
    prepareBootEnvironment: async () => {
      enterBootPreparation();
      await finished;
      return makeFakePrepared();
    },
  });

  env.parentPort.fire({
    type: 'init',
    opts: { contentDir: '/tmp/x', projectDir: '/tmp/x', port: 0, host: 'localhost' },
  });
  return {
    bootServer,
    reachedBootPreparation: Promise.race([entered, handle.readyPromise.then(() => {})]),
    finishBootPreparation,
  };
}

async function finishBootPreparationAndLetInitContinue(finish: () => void): Promise<void> {
  finish();
  await new Promise<void>((resolve) => setImmediate(resolve));
}

describe('setupUtility honours a shutdown that arrives before its init reaches bootServer', () => {
  test('exits 0 without calling bootServer when shutdown arrives while its init is still preparing the boot environment', async () => {
    const withoutShutdown = startUtilityWhoseBootPreparationWaits(buildEnv());
    await withoutShutdown.reachedBootPreparation;
    await finishBootPreparationAndLetInitContinue(withoutShutdown.finishBootPreparation);
    expect(withoutShutdown.bootServer).toHaveBeenCalledTimes(1);

    const env = buildEnv();
    const utility = startUtilityWhoseBootPreparationWaits(env);
    await utility.reachedBootPreparation;
    expect(utility.bootServer).not.toHaveBeenCalled();

    env.parentPort.fire({ type: 'shutdown' });
    await finishBootPreparationAndLetInitContinue(utility.finishBootPreparation);

    expect(utility.bootServer).not.toHaveBeenCalled();
    expect(env.exit.mock.calls).toEqual([[0]]);
  });
});

function startUtilityWhoseServerStartWaits(env: MockEnv) {
  const destroy = vi.fn(() => Promise.resolve());
  const { promise: reachedServerStart, resolve: enterServerStart } = Promise.withResolvers<void>();
  let settleServerStart!: (failure?: Error) => void;
  const serverStarted = new Promise<void>((resolve, reject) => {
    settleServerStart = (failure) => (failure === undefined ? resolve() : reject(failure));
  });
  const bootServer = vi.fn(async () => {
    enterServerStart();
    await serverStarted;
    return { port: 51290, destroy, degraded: [] as readonly string[] };
  });
  setupUtility({
    parentPort: env.parentPort,
    importServer: () =>
      Promise.resolve({
        bootServer,
      } as unknown as typeof import('@inkeep/open-knowledge-server')),
    exit: env.exit,
    parentPid: 99999,
    killProbe: env.killProbe,
    onSignal: (sig, h) => env.signalHandlers.set(sig, h),
    setInterval: (cb, ms) => {
      env.intervals.push({ cb, ms });
      return { unref: vi.fn(() => {}), clear: env.intervalCancel };
    },
    prepareBootEnvironment: fakePrepare(),
  });
  env.parentPort.fire({
    type: 'init',
    opts: { contentDir: '/tmp/x', projectDir: '/tmp/x', port: 0, host: 'localhost' },
  });
  return { destroy, reachedServerStart, settleServerStart };
}

async function nextTurn(): Promise<void> {
  await new Promise<void>((resolve) => setImmediate(resolve));
}

function postedTypes(env: MockEnv): unknown[] {
  return env.parentPort.postMessage.mock.calls.map(([msg]) => (msg as { type?: unknown }).type);
}

describe('setupUtility joins a server start still in progress when shutdown arrives', () => {
  test('waits for the server it is starting, shuts that server down, then exits 0 without announcing it ready', async () => {
    const env = buildEnv();
    const utility = startUtilityWhoseServerStartWaits(env);
    await utility.reachedServerStart;

    env.parentPort.fire({ type: 'shutdown' });
    await nextTurn();
    expect(env.exit).not.toHaveBeenCalled();

    utility.settleServerStart();
    await nextTurn();

    expect(utility.destroy).toHaveBeenCalledTimes(1);
    expect(env.exit.mock.calls).toEqual([[0]]);
    expect(postedTypes(env)).not.toContain('ready');
  });

  test('exits once when the server it is starting fails after shutdown arrived', async () => {
    const env = buildEnv();
    const utility = startUtilityWhoseServerStartWaits(env);
    await utility.reachedServerStart;

    env.parentPort.fire({ type: 'shutdown' });
    utility.settleServerStart(new Error('server start failed'));
    await nextTurn();

    expect(utility.destroy).not.toHaveBeenCalled();
    expect(env.exit.mock.calls).toEqual([[0]]);
  });
});

describe('setupUtility repeated shutdown', () => {
  test('a second shutdown resolves only after the first has finished draining the server', async () => {
    const env = buildEnv();
    let finishDestroy!: () => void;
    const destroy = vi.fn(() => {
      const { promise, resolve } = Promise.withResolvers<void>();
      finishDestroy = resolve;
      return promise;
    });
    const handle = setupUtility({
      parentPort: env.parentPort,
      importServer: () =>
        Promise.resolve({
          bootServer: () => Promise.resolve({ port: 51291, destroy, degraded: [] }),
        } as unknown as typeof import('@inkeep/open-knowledge-server')),
      exit: env.exit,
      parentPid: 99999,
      killProbe: env.killProbe,
      onSignal: (sig, h) => env.signalHandlers.set(sig, h),
      setInterval: (cb, ms) => {
        env.intervals.push({ cb, ms });
        return { unref: vi.fn(() => {}), clear: env.intervalCancel };
      },
      prepareBootEnvironment: fakePrepare(),
    });
    env.parentPort.fire({
      type: 'init',
      opts: { contentDir: '/tmp/x', projectDir: '/tmp/x', port: 0, host: 'localhost' },
    });
    await handle.readyPromise;

    const first = handle.shutdown('shutdown-ipc');
    let secondSettled = false;
    const second = handle.shutdown('SIGTERM').then(() => {
      secondSettled = true;
    });
    await nextTurn();

    expect(destroy).toHaveBeenCalledTimes(1);
    expect(secondSettled).toBe(false);
    finishDestroy();
    await Promise.all([first, second]);
    expect(env.exit.mock.calls).toEqual([[0]]);
  });
});