Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

12.8 KB
Raw Blame
import { existsSync, mkdirSync, readFileSync, realpathSync } from 'node:fs';
import { relative, resolve } from 'node:path';
import { isDevChannel } from '@inkeep/open-knowledge-core/constants/product';
import {
  ASSET_EXTENSIONS,
  EXECUTABLE_BLOCKLIST_EXTENSIONS,
  INLINE_RENDERABLE_EXTENSIONS,
} from '@inkeep/open-knowledge-core/constants/upload';
import { okUserHomeDir } from '@inkeep/open-knowledge-core/server';
import {
  AcpThreadManager,
  buildIngressPolicy,
  buildOkMcpStdioCommand,
  createAssetServeMiddleware,
  createCollaborationHost,
  createServer,
  getLogger,
  makeLazyEmbeddingsKeyStore,
  readAgentBrowserTools,
  releaseServerLock,
  updateServerLockPort,
} from '@inkeep/open-knowledge-server';
import sirv from 'sirv';
import type { Plugin, ViteDevServer } from 'vite';
import type { WebSocketServer } from 'ws';
import { parse as parseYaml } from 'yaml';
import { computeDevApiConfigResponse } from './api-config-handler.ts';
import { type AssetRouting, routeAssets } from './asset-routing.ts';
import {
  applyDevServerChannel,
  devServerCliArgs,
  workspaceCliEntry,
} from './dev-server-channel.ts';

let configureServerInvocations = 0;

const PLUGIN_DIR = import.meta.dirname ?? new URL('.', import.meta.url).pathname;
const PROJECT_ROOT = resolve(PLUGIN_DIR, '../../../..');

interface ContentConfig {
  dir: string;
}

export function resolveContentConfig(projectRoot: string): ContentConfig {
  const defaults: ContentConfig = { dir: projectRoot };
  const configPath = resolve(projectRoot, '.ok/config.yml');
  if (existsSync(configPath)) {
    try {
      const raw = readFileSync(configPath, 'utf-8');
      const parsed = parseYaml(raw) as Record<string, unknown> | null;
      const content = parsed?.content as Record<string, unknown> | undefined;
      if (typeof content?.dir === 'string') {
        defaults.dir = resolve(projectRoot, content.dir);
      }
    } catch (err) {
      console.warn('[hocuspocus] Failed to parse config:', err);
    }
  }
  return defaults;
}

const contentConfig = resolveContentConfig(PROJECT_ROOT);
const CONTENT_DIR = process.env.OK_TEST_CONTENT_DIR
  ? realpathSync(process.env.OK_TEST_CONTENT_DIR)
  : contentConfig.dir;
const CONTENT_ROOT = relative(PROJECT_ROOT, CONTENT_DIR);

mkdirSync(CONTENT_DIR, { recursive: true });

const isTestIsolated = Boolean(process.env.OK_TEST_CONTENT_DIR);
const gitEnabledForTest = isTestIsolated && process.env.OK_TEST_GIT_ENABLED === '1';

const SINGLE_DOC_REL_PATH = process.env.OK_TEST_SINGLE_DOC_REL_PATH || undefined;
const isEphemeralTest = isTestIsolated && SINGLE_DOC_REL_PATH !== undefined;
const TEST_PROJECT_DIR = process.env.OK_TEST_PROJECT_DIR
  ? realpathSync(process.env.OK_TEST_PROJECT_DIR)
  : undefined;

let exitHandlerRegistered = false;
let latestLockDir: string | null = null;

const VITE_WSS_CLOSE_TIMEOUT_MS = 5_000;

function closeWebSocketServer(wss: WebSocketServer): Promise<void> {
  return new Promise<void>((resolve, reject) => {
    let settled = false;
    const timer = setTimeout(() => {
      if (settled) return;
      settled = true;
      const terminationErrors: unknown[] = [];
      for (const client of wss.clients) {
        try {
          client.terminate();
        } catch (err) {
          terminationErrors.push(err);
        }
      }
      const timeoutError = new Error(
        `WebSocket server close timed out after ${VITE_WSS_CLOSE_TIMEOUT_MS}ms`,
      );
      reject(
        terminationErrors.length === 0
          ? timeoutError
          : new AggregateError(
              [timeoutError, ...terminationErrors],
              'WebSocket server close timed out and client termination failed',
            ),
      );
    }, VITE_WSS_CLOSE_TIMEOUT_MS);
    timer.unref?.();

    const settle = (err?: unknown): void => {
      if (settled) return;
      settled = true;
      clearTimeout(timer);
      if (err) reject(err);
      else resolve();
    };

    try {
      wss.close(settle);
    } catch (err) {
      settle(err);
    }
  });
}

type OkServerHost = Pick<ViteDevServer, 'httpServer' | 'middlewares'>;

type RuntimeTeardowns = Set<() => Promise<void>>;

export function hocuspocusPlugin(): Plugin {
  const activeRuntimeTeardowns: RuntimeTeardowns = new Set();
  return {
    name: 'hocuspocus',
    async buildEnd() {
      const results = await Promise.allSettled(
        [...activeRuntimeTeardowns].map((teardown) => teardown()),
      );
      const errors = results
        .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
        .map((result) => result.reason);
      if (errors.length > 0) throw new AggregateError(errors, 'Hocuspocus Vite teardown failed');
    },
    async configureServer(server) {
      await attachOkServer(server, { kind: 'dev-server' }, activeRuntimeTeardowns);
    },
  };
}

export function prebuiltHocuspocusPlugin(): Plugin {
  const activeRuntimeTeardowns: RuntimeTeardowns = new Set();
  return {
    name: 'hocuspocus:prebuilt',
    apply: 'serve',
    async configurePreviewServer(server) {
      const teardown = await attachOkServer(
        server,
        { kind: 'prebuilt', bundleDir: resolve(server.config.root, server.config.build.outDir) },
        activeRuntimeTeardowns,
      );
      const closePreview = server.close.bind(server);
      server.close = async () => {
        const results = await Promise.allSettled([closePreview(), teardown()]);
        const errors = results
          .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
          .map((result) => result.reason);
        if (errors.length > 0) throw new AggregateError(errors, 'Prebuilt preview close failed');
      };
    },
  };
}

async function attachOkServer(
  server: OkServerHost,
  assetRouting: AssetRouting,
  activeRuntimeTeardowns: RuntimeTeardowns,
): Promise<() => Promise<void>> {
  applyDevServerChannel(process.env);
  const localOpCliArgs = devServerCliArgs(PROJECT_ROOT, process.env);
  if (localOpCliArgs === undefined && isDevChannel(process.env)) {
    getLogger('hocuspocus').warn(
      { entry: workspaceCliEntry(PROJECT_ROOT) },
      'The workspace CLI is not built, so this dev server runs the open-knowledge on PATH as Stable for MCP, git credentials and local operations, and refuses sign-in, sign-out, token storage and clone. Run pnpm build in the checkout, then restart pnpm dev.',
    );
  }
  configureServerInvocations += 1;
  if (configureServerInvocations > 1) {
    console.warn(
      `[collab] configureServer invoked ${configureServerInvocations}× — Vite restarted; spinning up a fresh ServerInstance. The previous srv will be destroyed by its httpServer close handler.`,
    );
  } else {
    console.info(`[collab] configureServer invocation=1 pid=${process.pid}`);
  }

  const currentSrv = createServer({
    contentDir: CONTENT_DIR,
    projectDir: TEST_PROJECT_DIR ?? (isTestIsolated ? CONTENT_DIR : PROJECT_ROOT),
    contentRoot: isTestIsolated ? '' : CONTENT_ROOT,
    ...(isTestIsolated ? { configHomedirOverride: CONTENT_DIR } : {}),
    gitEnabled: isEphemeralTest ? false : !isTestIsolated || gitEnabledForTest,
    enableTestRoutes: true,
    quiet: true,
    embeddingsKeyStore: makeLazyEmbeddingsKeyStore(),
    capabilities: ['http', 'ws', 'ui'],
    ...(localOpCliArgs === undefined ? {} : { localOpCliArgs }),
    ...(isEphemeralTest ? { ephemeral: true, singleDocRelPath: SINGLE_DOC_REL_PATH } : {}),
  });

  latestLockDir = currentSrv.lockDir;
  if (!exitHandlerRegistered) {
    exitHandlerRegistered = true;
    process.once('exit', () => {
      if (latestLockDir === null) return;
      try {
        releaseServerLock(latestLockDir);
      } catch {}
    });
  }

  if (configureServerInvocations === 1) {
    getLogger('hocuspocus').info({ contentDir: CONTENT_DIR }, 'content dir');
  }

  server.httpServer?.once('listening', () => {
    const addr = server.httpServer?.address();
    if (typeof addr === 'object' && addr !== null) {
      updateServerLockPort(currentSrv.lockDir, addr.port, `http://localhost:${addr.port}`);
    }
  });

  const { hocuspocus, nativeApi, sessionManager, agentFocusBroadcaster, agentPresenceBroadcaster } =
    currentSrv;

  const acpThreadManager = isEphemeralTest
    ? null
    : new AcpThreadManager({
        contentDir: CONTENT_DIR,
        localDir: currentSrv.lockDir,
        globalDir: okUserHomeDir(),
        registry: currentSrv.acpRegistry,
        permissions: currentSrv.acpPermissions,
        sessionManager,
        agentPresenceBroadcaster,
        localApi: currentSrv.localApi,
        isExcludedPath: (rel) => currentSrv.contentFilter.isExcluded(rel),
        isIgnoredPath: (rel) => currentSrv.contentFilter.isPathIgnored(rel),
        getLoadedDocText: (docName) =>
          hocuspocus.documents.get(docName)?.getText('source').toString() ?? null,
        getServerUrl: () => {
          const addr = server.httpServer?.address();
          const port = typeof addr === 'object' && addr !== null ? addr.port : 5173;
          return `http://localhost:${port}`;
        },
        getMcpStdioCommand: () => {
          const addr = server.httpServer?.address();
          const port = typeof addr === 'object' && addr !== null ? addr.port : 5173;
          return buildOkMcpStdioCommand(localOpCliArgs, port, { log: getLogger('acp-threads') });
        },
        agentBrowserTools: () =>
          !isTestIsolated &&
          readAgentBrowserTools(PROJECT_ROOT, undefined, getLogger('acp-permissions')),
        log: getLogger('acp-threads'),
      });
  await acpThreadManager?.init();

  const collaborationHost = createCollaborationHost({
    hocuspocus,
    log: getLogger('hocuspocus'),
    sessionManager,
    agentFocusBroadcaster,
    agentPresenceBroadcaster,
    maintenanceCoordinator: currentSrv.maintenanceCoordinator,
    acpThreadManager,
  });
  server.httpServer?.prependListener('upgrade', collaborationHost.handleUpgrade);

  const assetMiddleware = createAssetServeMiddleware({
    contentDir: CONTENT_DIR,
    contentFilter: currentSrv.contentFilter,
    contentSirv: sirv(CONTENT_DIR, { dev: true, dotfiles: false }),
    inlineExtensions: INLINE_RENDERABLE_EXTENSIONS,
    assetExtensions: ASSET_EXTENSIONS,
    blocklistExtensions: EXECUTABLE_BLOCKLIST_EXTENSIONS,
    ingressPolicy: buildIngressPolicy({}),
    resolveTrackedFile: currentSrv.resolveTrackedFile,
  });
  server.middlewares.use(routeAssets(assetRouting, assetMiddleware));

  server.middlewares.use(async (req, res, next) => {
    const url = req.url?.split('?')[0];
    if (url?.startsWith('/api/')) {
      if (url === '/api/config') {
        const addr = server.httpServer?.address();
        const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
        const response = computeDevApiConfigResponse(req.method, port, isEphemeralTest);
        if (response) {
          for (const [name, value] of Object.entries(response.headers)) {
            res.setHeader(name, value);
          }
          res.statusCode = response.status;
          if (response.omitBody) {
            res.end();
          } else {
            res.end(response.body);
          }
          return;
        }
      }
      if (await nativeApi.dispatch(req, res)) return;
      // biome-ignore lint/suspicious/noExplicitAny: Hocuspocus `hooks()` has no exported payload type for onRequest
      await hocuspocus.hooks('onRequest', { request: req, response: res } as any);
      if (res.writableEnded || res.headersSent) return;
      res.statusCode = 404;
      res.setHeader('Content-Type', 'application/json');
      res.end(JSON.stringify({ error: 'API route not found', path: url }));
      return;
    }
    next();
  });

  let teardownPromise: Promise<void> | undefined;
  const teardown = (): Promise<void> => {
    teardownPromise ??= (async () => {
      const errors: unknown[] = [];
      const run = async (label: string, action: () => Promise<void>): Promise<void> => {
        try {
          await action();
        } catch (err) {
          errors.push(err);
          getLogger('hocuspocus').error({ err }, `Vite collaboration teardown failed: ${label}`);
        }
      };
      server.httpServer?.off('upgrade', collaborationHost.handleUpgrade);
      await run('ACP thread manager', async () => acpThreadManager?.destroy());
      await run('collaboration host', () => collaborationHost.shutdown());
      await run('WebSocket server', () => closeWebSocketServer(collaborationHost.wss));
      await run('server instance', () => currentSrv.destroy());
      if (errors.length > 0) throw new AggregateError(errors, 'Vite collaboration teardown failed');
    })();
    void teardownPromise.finally(() => activeRuntimeTeardowns.delete(teardown)).catch(() => {});
    return teardownPromise;
  };
  activeRuntimeTeardowns.add(teardown);
  server.httpServer?.on('close', () => {
    void teardown().catch((err) =>
      getLogger('hocuspocus').error({ err }, 'HTTP close fallback teardown failed'),
    );
  });

  getLogger('hocuspocus').info({}, 'WebSocket server ready on /collab');
  return teardown;
}