Function createServer

apps/api/src/server.ts:26–137

(config = loadConfig())

import { createQuestionLog } from './storage/questionLog.js';

export { loadConfig, ensureContentRoot, defaultContentRoot } from './config.js';
export type { ServerConfig } from './config.js';

export interface CreateServerOptions {
  /**
   * Override the RocketReach client factory. Production leaves this unset (the
   * real HTTPS client is used); tests inject a stub / a client with a fake
   * `fetch` so the suite never touches the network.
   */
  createRocketReachClient?: (options: RocketReachClientOptions) => RocketReachClient;
}

export function createServer(
  config = loadConfig(),
  options: CreateServerOptions = {},
): http.Server {
  ensureContentRoot(config.contentRoot);
  const pathResolver = createPathResolver(config.contentRoot);
  const repository = createFileRepository(pathResolver);
  const auditLog = createAuditLog(config.contentRoot);
  const proposalStore = createProposalStore(config.contentRoot);
  const questionLog = createQuestionLog(config.contentRoot);
  const integrationStore = createIntegrationStore(config.contentRoot);
  const patchIdempotency = createIdempotencyCache<PatchFileResponse>();
  const eventBus = createEventBus();
  // Surface out-of-band edits (direct file writes, git, another process) so the
  // human's view stays live even for changes that never hit the API.
  const watcher = createVaultWatcher({ contentRoot: config.contentRoot, eventBus });
  // A cached retrieval index so search / semantic / context don't re-read the
  // whole vault per query. It subscribes to the same bus, so any write (API or
  // out-of-band) invalidates it and the next query rebuilds — never stale.
  const vaultIndex = createVaultIndex({ repository, eventBus, contentRoot: config.contentRoot });

  // Optional "dream cycle": when MAINTENANCE_INTERVAL_MS is a positive number,
  // periodically scan the vault for hygiene problems (broken links, orphans,
  // near-duplicates) and file each fix as a proposal for human review. Off by
  // default (unset); on-demand scanning is always available via the endpoints.
  const maintenanceIntervalMs = Number(process.env.MAINTENANCE_INTERVAL_MS);
  let maintenanceTimer: NodeJS.Timeout | undefined;
  if (Number.isFinite(maintenanceIntervalMs) && maintenanceIntervalMs > 0) {
    maintenanceTimer = setInterval(() => {
      void runMaintenanceScan({ vaultIndex, proposalStore, eventBus, pathResolver }).catch(() => {
        // Best-effort: a scheduled scan must never crash the server.
      });
    }, maintenanceIntervalMs);
    // Don't keep the process (or a test's event loop) alive just for the scan.
    maintenanceTimer.unref?.();
  }

  // Optional outreach feedback loop: when FEEDBACK_INTERVAL_MS is a positive
  // number, periodically compare reviewed draft→final pairs and file each
  // distilled lesson as a proposal for human review. Off by default; on-demand
  // scanning is always available via `POST /api/feedback/scan`.
  const feedbackIntervalMs = Number(process.env.FEEDBACK_INTERVAL_MS);
  let feedbackTimer: NodeJS.Timeout | undefined;
  if (Number.isFinite(feedbackIntervalMs) && feedbackIntervalMs > 0) {
    feedbackTimer = setInterval(() => {
      void runFeedbackScan({ vaultIndex, proposalStore, eventBus, pathResolver }).catch(() => {