Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

17.9 KB
Raw Blame
import { rename, writeFile } from 'node:fs/promises';
import { isAbsolute, relative, resolve } from 'node:path';
import type { ServerRuntimeConfig } from '@inkeep/open-knowledge-core';
import type {
  BootedServer,
  BootServerOptions,
  Config,
  ServerAuthorityCollisionError,
  ServerExitReason,
} from '@inkeep/open-knowledge-server';
import type { UtilityInitCounters, UtilityInitPhase } from '../shared/boot-narration.ts';
import { type KeyringSmokeResult, runKeyringSmoke } from './keyring-smoke.ts';

export type { KeyringSmokeResult } from './keyring-smoke.ts';

export interface UtilityInitMessage {
  type: 'init';
  opts: Pick<
    BootServerOptions,
    | 'contentDir'
    | 'projectDir'
    | 'port'
    | 'host'
    | 'debounce'
    | 'maxDebounce'
    | 'localOpCliArgs'
    | 'reactShellDistDir'
    | 'terminalAuthAvailable'
  > & {
    didEnsureGit?: boolean;
    consentVersion?: number;
  };
}
export interface UtilityShutdownMessage {
  type: 'shutdown';
}
export interface UtilityDebugKeyringSmokeMessage {
  type: 'debug-keyring-smoke';
  correlationId: string;
}
export type UtilityIncomingMessage =
  | UtilityInitMessage
  | UtilityShutdownMessage
  | UtilityDebugKeyringSmokeMessage;

export interface UtilityReadyMessage {
  type: 'ready';
  port: number;
  apiOrigin: string;
}
export interface UtilityErrorMessage {
  type: 'error';
  message: string;
  stack?: string;
  kind?:
    | 'lock-collision'
    | 'mcp-server-stuck'
    | 'mcp-server-killed'
    | 'content-ownership'
    | 'content-ownership-unverified'
    | 'authority-registry';
  existingLock?: {
    pid: number;
    hostname: string;
    port: number;
    startedAt: string;
    worktreeRoot: string;
    kind?: 'interactive' | 'mcp-spawned';
    capabilities?: string[];
  };
}
export interface UtilityDegradedMessage {
  type: 'degraded';
  subsystems: readonly string[];
}
export interface UtilityDebugKeyringSmokeResultMessage {
  type: 'debug-keyring-smoke-result';
  correlationId: string;
  result: KeyringSmokeResult;
}
export interface UtilityInitPhaseMessage extends UtilityInitCounters {
  type: 'init-phase';
  phase: UtilityInitPhase;
}
export type UtilityOutgoingMessage =
  | UtilityReadyMessage
  | UtilityErrorMessage
  | UtilityDegradedMessage
  | UtilityDebugKeyringSmokeResultMessage
  | UtilityInitPhaseMessage;

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<UtilityServerModule>;
  exit: (code: number) => void;
  parentPid: number;
  killProbe: (pid: number, signal: number | string) => void;
  onSignal: (signal: 'SIGTERM' | 'SIGINT', handler: () => void) => void;
  setInterval: (cb: () => void, ms: number) => { unref?: () => void; clear: () => void };
  parentPollMs?: number;
  runSmoke?: () => Promise<KeyringSmokeResult>;
  env?: Record<string, string | undefined>;
  writeSmokeResult?: (path: string, contents: string) => Promise<void>;
  prepareBootEnvironment?: PrepareBootEnvironment;
  readInitCounters?: () => UtilityInitCounters;
}

function afterZodCompile<T>(load: () => Promise<T>): Promise<T> {
  return import('zod/compile').then(load);
}

function readOwnInitCounters(): UtilityInitCounters {
  const cpu = process.cpuUsage();
  return {
    uptimeMs: Math.round(process.uptime() * 1000),
    cpuUserMs: Math.round(cpu.user / 1000),
    cpuSystemMs: Math.round(cpu.system / 1000),
  };
}

export interface PreparedBootEnvironment {
  config: Config;
  contentDir: string;
  contentRoot: string | undefined;
  configValid: boolean;
  serverRuntime: ServerRuntimeConfig;
  degradedHints?: readonly string[];
}

export type PrepareBootEnvironment = (
  ipcOpts: UtilityInitMessage['opts'],
  onPhase?: (phase: UtilityInitPhase) => void,
) => Promise<PreparedBootEnvironment>;

export type UtilityShutdownReason = 'parent-died' | 'shutdown-ipc' | 'SIGTERM' | 'SIGINT';

const SERVER_EXIT_REASONS: Record<UtilityShutdownReason, ServerExitReason> = {
  'parent-died': 'parent-exit',
  'shutdown-ipc': 'parent-exit',
  SIGTERM: 'external-signal',
  SIGINT: 'external-signal',
};

export interface UtilityHandle {
  readyPromise: Promise<UtilityReadyMessage>;
  stopParentPoll(): void;
  shutdown(reason: UtilityShutdownReason): Promise<void>;
}

export function setupUtility(deps: SetupUtilityDeps): UtilityHandle {
  let booted: UtilityBootedServer | null = null;
  let parentPollHandle: { unref?: () => void; clear: () => void } | null = null;
  let initInFlight: Promise<void> | null = null;
  let shutdownInFlight: Promise<void> | null = null;
  const {
    promise: readyPromise,
    resolve: resolveReady,
    reject: rejectReady,
  } = Promise.withResolvers<UtilityReadyMessage>();

  function startParentPoll() {
    const pollMs = deps.parentPollMs ?? 5000;
    parentPollHandle = deps.setInterval(() => {
      try {
        deps.killProbe(deps.parentPid, 0);
      } catch (err) {
        const code = (err as NodeJS.ErrnoException).code;
        if (code === 'EPERM' || code === 'ESRCH') {
          void shutdown('parent-died');
          return;
        }
        console.warn('[utility] parent-poll unexpected errno — continuing', {
          code: code ?? '(missing)',
          parentPid: deps.parentPid,
        });
      }
    }, pollMs);
    parentPollHandle.unref?.();
  }

  function stopParentPoll() {
    parentPollHandle?.clear();
    parentPollHandle = null;
  }

  function shutdown(reason: UtilityShutdownReason): Promise<void> {
    shutdownInFlight ??= drainAndExit(reason);
    return shutdownInFlight;
  }

  async function drainAndExit(reason: UtilityShutdownReason): Promise<void> {
    stopParentPoll();
    await initInFlight;
    let drainOk = true;
    if (booted) {
      try {
        await booted.destroy(
          SERVER_EXIT_REASONS[reason],
          reason === 'SIGTERM' || reason === 'SIGINT' ? { signal: reason } : undefined,
        );
      } catch (err) {
        drainOk = false;
        deps.parentPort?.postMessage({
          type: 'error',
          message: `destroy failed during ${reason}: ${(err as Error).message}`,
          stack: (err as Error).stack,
        });
      }
    }
    console.warn('[utility] shutdown finished, exiting', {
      reason,
      destroyResolved: booted !== null && drainOk,
      exitCode: drainOk ? 0 : 1,
    });
    deps.exit(drainOk ? 0 : 1);
  }

  const readInitCounters = deps.readInitCounters ?? readOwnInitCounters;

  function markInitPhase(phase: UtilityInitPhase): void {
    deps.parentPort?.postMessage({ type: 'init-phase', phase, ...readInitCounters() });
  }

  async function handleInit(msg: UtilityInitMessage) {
    try {
      markInitPhase('init-received');
      const [server, cli, serverNamespace] = await Promise.all([
        deps.importServer(),
        afterZodCompile(() => import('@inkeep/open-knowledge')),
        afterZodCompile(() => import('@inkeep/open-knowledge-server')),
      ]);
      markInitPhase('imports-resolved');
      cli.registerWindowsProcessStartReader(serverNamespace.getLogger('process-start'));
      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, markInitPhase);
      if (shutdownInFlight !== null) return;

      if (env.OK_DEBUG_DESKTOP_BOOT_TRACE === '1') {
        console.warn(
          `[desktop-boot-trace] projectDir=${projectDir} contentRoot=${JSON.stringify(
            prepared.contentRoot,
          )} resolvedContentDir=${prepared.contentDir} configValid=${prepared.configValid}`,
        );
      }

      const tokenStore = makeLazyProbeTokenStore();
      const embeddingsKeyStore = makeLazyEmbeddingsKeyStore();

      const bootOpts: BootServerOptions = {
        ...msg.opts,
        contentDir: prepared.contentDir,
        contentRoot: prepared.contentRoot,
        config: prepared.config,
        serverRuntime: prepared.serverRuntime,
        bind: prepared.serverRuntime.bind,
        idleShutdownMs: null,
        skipAutoInit: true,
        autoInitFn: undefined,
        detectGh,
        detectGhAccounts,
        tokenStore,
        embeddingsKeyStore,
        mcpTomlEditor: getNativeTomlMcpEditor(),
        probeHarnessManagedMcpEntry: (editorId, agentCwd) =>
          probeOwnManagedEditorMcpEntry(editorId, agentCwd),
        probePiAcpBridge: (agentCwd) => probePiBridgeState(agentCwd),
        ensurePiAcpBridge: (agentCwd, approvedCanonicalCwd) =>
          ensurePiBridge(agentCwd, undefined, undefined, undefined, approvedCanonicalCwd),
        serveContentAssets: true,
        terminalAuthAvailable: msg.opts.terminalAuthAvailable === true,
        ...(msg.opts.reactShellDistDir ? { reactShellDistDir: msg.opts.reactShellDistDir } : {}),
      };

      const requestedPort = prepared.serverRuntime.port ?? msg.opts.port;
      markInitPhase('boot-server-started');
      try {
        booted = await server.bootServer({ ...bootOpts, port: requestedPort });
      } catch (err) {
        if (isFixedPort(requestedPort) && isAddressInUse(err)) {
          console.warn(
            `[boot] pinned server.port ${requestedPort} is already in use — falling back to an ephemeral port`,
          );
          booted = await server.bootServer({ ...bootOpts, port: 0 });
        } else {
          throw err;
        }
      }
      if (shutdownInFlight !== null) return;
      const readyMsg: UtilityReadyMessage = {
        type: 'ready',
        port: booted.port,
        apiOrigin: `http://localhost:${booted.port}`,
      };
      deps.parentPort?.postMessage(readyMsg);
      resolveReady(readyMsg);

      const mergedDegraded: readonly string[] = [
        ...booted.degraded,
        ...(prepared.degradedHints ?? []),
      ];
      if (mergedDegraded.length > 0) {
        deps.parentPort?.postMessage({
          type: 'degraded',
          subsystems: mergedDegraded,
        });
      }
    } 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,
        stack: (err as Error).stack,
      };
      const errName = err && typeof err === 'object' ? (err as Error).name : '';
      if (errName === 'ServerLockCollisionError') {
        const existing = (err as { existing?: UtilityErrorMessage['existingLock'] }).existing;
        if (existing) {
          errMsg.kind = 'lock-collision';
          errMsg.existingLock = existing;
        }
      } else if (errName === 'ServerAuthorityCollisionError') {
        errMsg.kind =
          (err as ServerAuthorityCollisionError).verifiedLease === false
            ? 'content-ownership-unverified'
            : 'content-ownership';
      } else if (errName === 'ServerAuthorityRegistryError') {
        errMsg.kind = 'authority-registry';
      }
      const isGitPreflightFailure =
        errName === 'GitNotAvailableError' ||
        errName === 'GitProbeTimeoutError' ||
        errName === 'GitTooOldError';
      deps.parentPort?.postMessage(errMsg);
      if (shutdownInFlight !== null) return;
      rejectReady(err as Error);
      deps.exit(isGitPreflightFailure ? 78 : 1);
    }
  }

  const runSmoke = deps.runSmoke ?? runKeyringSmoke;
  const env = deps.env ?? (process.env as Record<string, string | undefined>);
  const writeSmokeResult = deps.writeSmokeResult ?? defaultWriteSmokeResult;

  async function handleDebugKeyringSmoke(msg: UtilityDebugKeyringSmokeMessage): Promise<void> {
    const result = await runSmoke();
    deps.parentPort?.postMessage({
      type: 'debug-keyring-smoke-result',
      correlationId: msg.correlationId,
      result,
    });
  }

  function registerMessageListener(): void {
    deps.parentPort?.on('message', (event) => {
      const msg = event.data as UtilityIncomingMessage;
      if (msg?.type === 'init') {
        initInFlight = handleInit(msg);
      } else if (msg?.type === 'shutdown') {
        void shutdown('shutdown-ipc');
      } else if (msg?.type === 'debug-keyring-smoke') {
        void handleDebugKeyringSmoke(msg);
      }
    });
  }

  async function runBootAutoSmoke(): Promise<void> {
    const result = await runSmoke();
    const outPath = env.OK_DEBUG_KEYRING_SMOKE_OUT;
    if (outPath && outPath.length > 0) {
      try {
        await writeSmokeResult(outPath, `${JSON.stringify(result)}\n`);
      } catch (err) {
        console.warn('[utility] auto-smoke write failed', {
          err: (err as Error).message,
          outPath,
        });
      }
    }
    deps.parentPort?.postMessage({
      type: 'debug-keyring-smoke-result',
      correlationId: 'auto-boot',
      result,
    });
    if (env.OK_DEBUG_KEYRING_SMOKE_EXIT === '1') {
      deps.exit(0);
      return;
    }
    registerMessageListener();
  }

  if (env.OK_DEBUG_KEYRING_SMOKE === '1') {
    void runBootAutoSmoke();
  } else {
    registerMessageListener();
  }

  deps.onSignal('SIGTERM', () => void shutdown('SIGTERM'));
  deps.onSignal('SIGINT', () => void shutdown('SIGINT'));

  startParentPoll();

  return {
    readyPromise,
    stopParentPoll,
    shutdown,
  };
}

async function defaultWriteSmokeResult(path: string, contents: string): Promise<void> {
  const tmp = `${path}.tmp`;
  await writeFile(tmp, contents, { encoding: 'utf-8' });
  await rename(tmp, path);
}

function isFixedPort(port: number | undefined): port is number {
  return typeof port === 'number' && port > 0;
}

function isAddressInUse(err: unknown): boolean {
  return (
    typeof err === 'object' && err !== null && (err as { code?: unknown }).code === 'EADDRINUSE'
  );
}

export async function resolveDesktopServerRuntime(projectDir: string): Promise<{
  config: Config;
  configValid: boolean;
  serverRuntime: ServerRuntimeConfig;
}> {
  const [{ loadConfig }, { resolveServerRuntimeConfig }, { ConfigSchema }] = await Promise.all([
    afterZodCompile(() => import('@inkeep/open-knowledge')),
    afterZodCompile(() => import('@inkeep/open-knowledge-core')),
    afterZodCompile(() => import('@inkeep/open-knowledge-server')),
  ]);
  let config: Config;
  let configValid: boolean;
  try {
    const result = loadConfig(projectDir);
    config = result.config;
    configValid = true;
    for (const diag of result.diagnostics) {
      const extra =
        'detail' in diag ? `: ${diag.detail}` : 'path' in diag ? `: ${diag.path.join('.')}` : '';
      console.warn(`[config] ${diag.code}${extra}`);
    }
    for (const { from, to } of result.sidelined) {
      console.warn(
        `[config] ${from} could not be parsed — moved to ${to}; booting on the remaining layers.`,
      );
    }
  } catch (err) {
    const detail = err instanceof Error ? err.message : String(err);
    console.warn(`[config] desktop boot config invalid — using schema defaults: ${detail}`);
    config = ConfigSchema.parse({});
    configValid = false;
  }
  return { config, configValid, serverRuntime: resolveServerRuntimeConfig(config) };
}

async function defaultPrepareBootEnvironment(
  ipcOpts: UtilityInitMessage['opts'],
  onPhase?: (phase: UtilityInitPhase) => void,
): Promise<PreparedBootEnvironment> {
  const projectDir = ipcOpts.projectDir ?? ipcOpts.contentDir;
  const { ensureProjectGit, initContent } = await afterZodCompile(
    () => import('@inkeep/open-knowledge-server'),
  );

  const degradedHints: string[] = [];
  if (ipcOpts.didEnsureGit !== true) {
    const result = await ensureProjectGit(projectDir);
    onPhase?.('project-git-ensured');
    if (result.repaired === true) {
      degradedHints.push('project-git-shell-only');
    }
  }

  initContent(projectDir);

  const { config, configValid, serverRuntime } = await resolveDesktopServerRuntime(projectDir);

  const contentDir = resolveContentDir(projectDir, config, ipcOpts.contentDir);
  const rawContentDir = config.content.dir;
  const contentRoot =
    typeof rawContentDir === 'string' && rawContentDir.length > 0 && rawContentDir !== '.'
      ? rawContentDir
      : undefined;
  return {
    config,
    contentDir,
    contentRoot,
    configValid,
    serverRuntime,
    degradedHints: degradedHints.length > 0 ? degradedHints : undefined,
  };
}

export function resolveContentDir(
  projectDir: string,
  config: Config,
  ipcFallback: string | undefined,
): string {
  const fallback = ipcFallback ?? projectDir;
  const configContentDir = config.content.dir;
  if (
    typeof configContentDir !== 'string' ||
    configContentDir.length === 0 ||
    configContentDir === '.'
  ) {
    return fallback;
  }
  const resolved = isAbsolute(configContentDir)
    ? configContentDir
    : resolve(projectDir, configContentDir);
  const rel = relative(projectDir, resolved);
  if (rel.startsWith('..') || isAbsolute(rel)) {
    console.warn(
      `[config] content.dir=${JSON.stringify(configContentDir)} resolves outside projectDir — using IPC fallback`,
    );
    return fallback;
  }
  return resolved;
}

if ((process as NodeJS.Process & { parentPort?: unknown }).parentPort) {
  setupUtility({
    parentPort: (process as NodeJS.Process & { parentPort: SetupUtilityDeps['parentPort'] })
      .parentPort,
    importServer: () => afterZodCompile(() => import('@inkeep/open-knowledge-server')),
    exit: (code) => process.exit(code),
    parentPid: process.ppid,
    killProbe: (pid, signal) => {
      process.kill(pid, signal as NodeJS.Signals | 0);
    },
    onSignal: (signal, handler) => {
      process.on(signal, handler);
    },
    setInterval: (cb, ms) => {
      const handle = setInterval(cb, ms);
      return {
        unref: () => handle.unref(),
        clear: () => clearInterval(handle),
      };
    },
  });
}