Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

36.1 KB
Raw Blame
import { spawn as nativeSpawn } from 'node:child_process';
import { existsSync as fsExistsSync, realpathSync } from 'node:fs';
import { rm } from 'node:fs/promises';
import type { Server as HttpServer } from 'node:http';
import { homedir, tmpdir } from 'node:os';
import { basename, dirname, resolve as pathResolve } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
import {
  applyConfigOverlay,
  currentCliCommandName,
  DEFAULT_SERVER_HOST,
  type EnvConfigLayer,
  EnvVarError,
  IDLE_SHUTDOWN_DURATION_RE,
  idleShutdownToMs,
  OK_DIR,
  resolveEnvConfigLayer,
  resolveServerRuntimeConfig,
  type ServerRuntimeConfig,
} from '@inkeep/open-knowledge-core';
import { readConfigSafely, resolveConfigPath } from '@inkeep/open-knowledge-core/server';
import {
  type BootedServer,
  type Config,
  EPHEMERAL_PROJECT_DIR_PREFIX,
  isProjectRoot,
  lockAdvertisesUi,
  type PinoLogger,
  prepareSingleFileOpen,
  type ServerExitDetail,
  type ServerExitReason,
} from '@inkeep/open-knowledge-server';
import { Command, InvalidArgumentError, Option } from 'commander';
import { makeLazyEmbeddingsKeyStore } from '../auth/embeddings-key-store.ts';
import { detectGh, detectGhAccounts } from '../auth/gh-detect.ts';
import { makeLazyProbeTokenStore } from '../auth/token-store.ts';
import { PACKAGE_VERSION } from '../constants.ts';
import { createCliStepExecutor } from '../integrations/registry-apply.ts';
import { createCliProbeResolver } from '../integrations/registry-probes.ts';
import { userSkillPresentAnywhere } from '../integrations/write-user-skill.ts';
import { getNativeTomlMcpEditor } from '../native/toml-config-engine.ts';
import { probeOwnManagedEditorMcpEntry } from './acp-harness-probe.ts';
import {
  createRealDetectDeps,
  detectDesktop,
  launchDesktop,
  notFoundMessage,
} from './desktop-dispatch.ts';
import { ensurePiBridge, probePiBridgeState } from './pi-acp-bridge.ts';
import type { LaunchJsonRepairResult } from './repair-launch-json.ts';
import type { RepairResult } from './repair-mcp-configs.ts';

const DEFAULT_IDLE_THRESHOLD_MS = 30 * 60 * 1000;

export function resolveHost(
  opts: { bind?: string[] },
  env: { HOST?: string | undefined; [key: string]: string | undefined },
): string {
  return opts.bind?.[0] ?? env.HOST ?? DEFAULT_SERVER_HOST;
}

export type OnlyModule = 'server';

export function parseOnlyModule(value: string): OnlyModule {
  if (value === 'server') return value;
  throw new InvalidArgumentError("--only must be 'server'");
}

export function resolveBundledReactShellDir(
  existsFn: (path: string) => boolean = fsExistsSync,
  cliDir: string = import.meta.dirname ?? new URL('.', import.meta.url).pathname,
): string | undefined {
  const candidates = [
    pathResolve(cliDir, 'public'),
    pathResolve(cliDir, '../../app/dist'),
    pathResolve(cliDir, '../../../app/dist'),
  ];
  if (existsFn(pathResolve(cliDir, '../../app.asar'))) {
    candidates.push(pathResolve(cliDir, '../../app'));
  }
  return candidates.find((p) => existsFn(p));
}

export function resolveStartShellDir(input: {
  explicitDir: string | undefined;
  only: OnlyModule | undefined;
  findBundledDir: () => string | undefined;
}): { dir: string | undefined; missingBundle: boolean } {
  if (input.explicitDir !== undefined) return { dir: input.explicitDir, missingBundle: false };
  if (input.only === 'server') return { dir: undefined, missingBundle: false };
  const dir = input.findBundledDir();
  return { dir, missingBundle: dir === undefined };
}

export function parseIdleShutdownFlag(value: string): string {
  if (value === 'off') return 'off';
  if (!IDLE_SHUTDOWN_DURATION_RE.test(value)) {
    throw new InvalidArgumentError("--idle-shutdown must be 'off' or a duration like 90s, 30m, 2h");
  }
  return value;
}

export function isLoopbackHost(host: string): boolean {
  return host === 'localhost' || host === '::1' || host === '[::1]' || host.startsWith('127.');
}

export function shouldWarnHostOverridesMultiBind(input: {
  flagBindSet: boolean;
  okBindSet: boolean;
  hostEnvSet: boolean;
  fileBindCount: number;
}): boolean {
  return !input.flagBindSet && !input.okBindSet && input.hostEnvSet && input.fileBindCount > 1;
}

export function shouldOpenBrowser(input: {
  openBrowser: boolean;
  explicitOn: boolean;
  host: string;
  isTTY: boolean;
  ephemeral: boolean;
  only: OnlyModule | undefined;
  servesUi: boolean;
}): boolean {
  if (!input.openBrowser) return false;
  if (input.ephemeral || input.only === 'server') return false;
  if (!input.servesUi) return false;
  return (input.explicitOn || isLoopbackHost(input.host)) && input.isTTY;
}

function parseHttpOriginFlag(flagName: string, value: string): string {
  let parsed: URL;
  try {
    parsed = new URL(value);
  } catch {
    throw new InvalidArgumentError(`${flagName} is not a valid URL: ${value}`);
  }
  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
    throw new InvalidArgumentError(`${flagName} must be an http(s) origin (got: ${value})`);
  }
  return value;
}

export function parseExternalUrlFlag(value: string): string {
  return parseHttpOriginFlag('--external-url', value);
}

const PROCESS_TITLE_PROJECT_NAME_MAX = 64;

export function deriveServerProcessTitle(cwd: string): string {
  const raw = basename(cwd);
  const sanitized = raw
    .replace(/[^\x20-\x7E]/g, '')
    .trim()
    .slice(0, PROCESS_TITLE_PROJECT_NAME_MAX);
  const projectName = sanitized.length > 0 ? sanitized : 'unknown';
  return `open-knowledge-server ${projectName}`;
}

export class OkDirMissingError extends Error {
  readonly cwd: string;
  constructor(cwd: string) {
    super(
      `This directory isn't set up yet. Run \`${currentCliCommandName()} init\` first, then \`${currentCliCommandName()} start\` again.`,
    );
    this.name = 'OkDirMissingError';
    this.cwd = cwd;
  }
}

export class EphemeralProjectDirNotThrowawayError extends Error {
  readonly projectDir: string;
  constructor(projectDir: string) {
    super(
      `--project-dir must be a throwaway ${EPHEMERAL_PROJECT_DIR_PREFIX}* directory under the OS temp dir. ` +
        `Refusing to write ephemeral session state into ${projectDir}. ` +
        `Omit --project-dir to let ${currentCliCommandName()} start create (and clean up) its own.`,
    );
    this.name = 'EphemeralProjectDirNotThrowawayError';
    this.projectDir = projectDir;
  }
}

export function isReapableEphemeralProjectDir(
  dir: string,
  deps: { tmpdirFn?: () => string; realpathFn?: (path: string) => string } = {},
): boolean {
  const tmpdirFn = deps.tmpdirFn ?? tmpdir;
  const realpathFn = deps.realpathFn ?? realpathSync;
  const canonical = (path: string): string | null => {
    try {
      return realpathFn(path);
    } catch (err) {
      return (err as NodeJS.ErrnoException).code === 'ENOENT' ? pathResolve(path) : null;
    }
  };
  const literal = pathResolve(dir);
  let target: string | null;
  try {
    target = realpathFn(literal);
  } catch (err) {
    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
      const parent = canonical(dirname(literal));
      target = parent === null ? null : pathResolve(parent, basename(literal));
    } else {
      target = null;
    }
  }
  if (target === null) return false;
  const tmpRoot = canonical(tmpdirFn());
  if (tmpRoot === null) return false;
  return dirname(target) === tmpRoot && basename(target).startsWith(EPHEMERAL_PROJECT_DIR_PREFIX);
}

export function withEphemeralTempDirReap(
  handler: () => Promise<void>,
  projectDir: string,
  rmFn: (dir: string) => Promise<void> = (dir) => rm(dir, { recursive: true, force: true }),
): () => Promise<void> {
  return async () => {
    try {
      await handler();
    } finally {
      if (isReapableEphemeralProjectDir(projectDir)) {
        try {
          await rmFn(projectDir);
        } catch (err) {
          process.stderr.write(
            `[start] ephemeral temp dir reap failed for ${projectDir}: ${err instanceof Error ? err.message : String(err)}\n`,
          );
        }
      } else {
        process.stderr.write(
          `[start] leaving ${projectDir} in place: only ${EPHEMERAL_PROJECT_DIR_PREFIX}* dirs under the OS temp dir are removed on ephemeral teardown\n`,
        );
      }
    }
  };
}

export function withIdleShutdownProcessExit(
  handler: () => Promise<void>,
  deps: {
    log?: { info: (obj: object, msg: string) => void; error: (obj: object, msg: string) => void };
    exit?: (code: number) => void;
    getActiveHandles?: () => unknown[] | null;
  } = {},
): () => Promise<void> {
  const exit = deps.exit ?? ((code: number) => process.exit(code));
  const getActiveHandles =
    deps.getActiveHandles ??
    (() => {
      const probe = (process as unknown as { _getActiveHandles?: () => unknown[] })
        ._getActiveHandles;
      return probe ? probe.call(process) : null;
    });
  return async () => {
    let failed = false;
    try {
      await handler();
    } catch (err) {
      failed = true;
      deps.log?.error({ err }, 'idle-shutdown: destroy failed — exiting anyway');
    } finally {
      let handleSummary: Record<string, number> | null = null;
      try {
        const handles = getActiveHandles();
        if (handles !== null) {
          handleSummary = {};
          for (const handle of handles) {
            const name =
              (handle as { constructor?: { name?: string } } | null)?.constructor?.name ??
              'unknown';
            handleSummary[name] = (handleSummary[name] ?? 0) + 1;
          }
        }
      } catch {
        handleSummary = null;
      }
      deps.log?.info(
        {
          event: 'idle-shutdown-exit',
          exitCode: failed ? 1 : 0,
          openHandles: handleSummary ?? {},
          handlesAvailable: handleSummary !== null,
        },
        'idle-shutdown: teardown finished — exiting process',
      );
      exit(failed ? 1 : 0);
    }
  };
}

interface BootStartServerOptions {
  config: Config;
  cwd: string;
  host: string;
  port?: number;
  skipAutoInit?: boolean;
  idleThresholdMs?: number | null;
  serverRuntime?: ServerRuntimeConfig;
  bind?: readonly string[];
  idleExit?: (code: number) => void;
  log?: PinoLogger;
  repairMcpConfigsFn?: (opts: {
    projectDir: string;
    reclaimDisableEnv: string | null;
    logger?: (event: { event: string; severity: 'info' | 'warn' }) => void;
  }) => RepairResult;
  repairLaunchJsonFn?: (opts: {
    projectDir: string;
    reclaimDisableEnv: string | null;
    logger?: (event: { event: string; severity: 'info' | 'warn' }) => void;
  }) => LaunchJsonRepairResult;
  serveContentAssets?: boolean;
  reactShellDistDir?: string;
  singleFile?: string;
  projectDir?: string;
  terminalAuthAvailable?: boolean;
}

export interface BootedStartServer {
  httpServer: HttpServer;
  destroy: (reason?: ServerExitReason, detail?: ServerExitDetail) => Promise<void>;
  lockDir: string;
  contentDir: string;
  port: number;
  ready: Promise<void>;
  degraded: readonly string[];
}

export async function bootStartServer(opts: BootStartServerOptions): Promise<BootedStartServer> {
  const { config, cwd, host } = opts;
  const skipAutoInit = opts.skipAutoInit ?? false;
  const idleThresholdMs =
    opts.idleThresholdMs === undefined ? DEFAULT_IDLE_THRESHOLD_MS : opts.idleThresholdMs;

  const { existsSync, mkdirSync } = await import('node:fs');
  const { basename, dirname, resolve } = await import('node:path');
  const {
    bootServer,
    createEphemeralProjectDir,
    getLogger,
    resolveContentDir,
    resolveLockDir,
    seedEphemeralProjectDir,
    waitForServerLockDrain,
  } = await import('@inkeep/open-knowledge-server');

  const log = opts.log ?? getLogger('start');

  const ephemeral = opts.singleFile !== undefined;
  const ephemeralFile = ephemeral
    ? prepareSingleFileOpen(opts.singleFile as string).canonicalFilePath
    : undefined;
  const ephemeralContentDir = ephemeralFile ? dirname(ephemeralFile) : undefined;
  const ephemeralDocRelPath = ephemeralFile ? basename(ephemeralFile) : undefined;

  let ephemeralProjectDir: string | undefined;
  let ownsEphemeralProjectDir = false;
  if (ephemeralContentDir !== undefined) {
    if (opts.projectDir !== undefined) {
      ephemeralProjectDir = opts.projectDir;
      if (!isReapableEphemeralProjectDir(ephemeralProjectDir)) {
        throw new EphemeralProjectDirNotThrowawayError(ephemeralProjectDir);
      }
      if (!existsSync(resolve(ephemeralProjectDir, OK_DIR, 'config.yml'))) {
        seedEphemeralProjectDir(ephemeralProjectDir, ephemeralContentDir);
      }
    } else {
      ephemeralProjectDir = createEphemeralProjectDir(ephemeralContentDir);
      ownsEphemeralProjectDir = true;
    }
  }
  const reapOwnedEphemeralDir = async (): Promise<void> => {
    if (!ownsEphemeralProjectDir || ephemeralProjectDir === undefined) return;
    if (!isReapableEphemeralProjectDir(ephemeralProjectDir)) {
      log.warn(
        { ephemeralProjectDir },
        '[start] refusing to reap self-provisioned ephemeral dir: no longer resolves to an ok-ephemeral-* temp dir',
      );
      return;
    }
    try {
      await rm(ephemeralProjectDir, { recursive: true, force: true });
    } catch (err) {
      log.warn(
        { err, ephemeralProjectDir },
        '[start] failed to reap self-provisioned ephemeral temp dir',
      );
    }
  };
  const reapDirOnIdle = ephemeralProjectDir;

  if (!ephemeral) {
    if (!skipAutoInit && !isProjectRoot(cwd)) {
      throw new OkDirMissingError(cwd);
    }

    const reclaimDisableEnv = process.env.OK_RECLAIM_DISABLE ?? null;

    const reclaimEventLogger = (event: { event: string; severity: 'info' | 'warn' }) => {
      if (event.severity === 'info') log.debug({ event }, '[start] reclaim sweep event');
      else log.warn({ event }, '[start] reclaim sweep reported a problem');
    };

    try {
      const repair =
        opts.repairMcpConfigsFn ?? (await import('./repair-mcp-configs.ts')).repairMcpConfigs;
      const sweep = repair({ projectDir: cwd, reclaimDisableEnv, logger: reclaimEventLogger });
      const unhealed = sweep.outcomes.filter(
        (o) =>
          o.outcome !== 'no-entry' &&
          o.outcome !== 'canonical' &&
          o.outcome !== 'repaired' &&
          o.outcome !== 'foreign',
      );
      if (unhealed.length > 0) {
        log.warn({ unhealed }, '[start] reclaim sweep left entries it could not heal');
      }
    } catch (err) {
      log.warn({ err }, '[start] mcp-config repair sweep failed; continuing');
    }

    try {
      const repair =
        opts.repairLaunchJsonFn ?? (await import('./repair-launch-json.ts')).repairLaunchJson;
      repair({ projectDir: cwd, reclaimDisableEnv, logger: reclaimEventLogger });
    } catch (err) {
      log.warn({ err }, '[start] launch.json repair sweep failed; continuing');
    }
  }

  const contentDir = ephemeralContentDir ?? resolveContentDir(config, cwd);
  if (!ephemeral && !existsSync(contentDir)) {
    mkdirSync(contentDir, { recursive: true });
    log.info({ contentDir }, 'Created content directory');
  }

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

  let booted: BootedServer;
  try {
    {
      const drainLockDir = resolveLockDir(ephemeralProjectDir ?? cwd);
      const drainWaitStartedAt = Date.now();
      const drainOutcome = await waitForServerLockDrain(drainLockDir);
      if (drainOutcome !== 'no-drain') {
        log.info(
          {
            event: 'start-waited-for-draining-predecessor',
            outcome: drainOutcome,
            waitedMs: Date.now() - drainWaitStartedAt,
            drainLockDir,
          },
          drainOutcome === 'released'
            ? '[start] predecessor server finished draining — proceeding'
            : '[start] predecessor server still draining after wait — proceeding to collide',
        );
      }
    }

    booted = await bootServer({
      config,
      contentDir,
      projectDir: ephemeralProjectDir ?? cwd,
      contentRoot: ephemeral ? undefined : config.content.dir,
      port: opts.port,
      host,
      quiet: false,
      detectGh,
      detectGhAccounts,
      tokenStore,
      embeddingsKeyStore,
      mcpTomlEditor: getNativeTomlMcpEditor(),
      ...(ephemeral
        ? {
            ephemeral: true as const,
            singleDocRelPath: ephemeralDocRelPath,
            gitEnabled: false as const,
            gitPreflight: () => ({
              ok: true as const,
              version: '0.0.0',
              resolvedPath: 'git',
              source: 'PATH' as const,
            }),
          }
        : {}),
      localOpCliArgs: [process.execPath, process.argv[1]],
      probeHarnessManagedMcpEntry: (editorId, agentCwd) =>
        probeOwnManagedEditorMcpEntry(editorId, agentCwd),
      probePiAcpBridge: (agentCwd) => probePiBridgeState(agentCwd),
      ensurePiAcpBridge: (agentCwd, approvedCanonicalCwd) =>
        ensurePiBridge(agentCwd, undefined, undefined, undefined, approvedCanonicalCwd),
      agentIntegrations: (() => {
        const registryCtx = { cwd: ephemeralProjectDir ?? cwd, home: homedir(), env: process.env };
        return {
          probe: createCliProbeResolver(registryCtx),
          execute: createCliStepExecutor(registryCtx),
          userSkillPresentAnywhere,
        };
      })(),
      idleShutdownMs: idleThresholdMs,
      ...(opts.serverRuntime !== undefined ? { serverRuntime: opts.serverRuntime } : {}),
      ...(opts.bind !== undefined ? { bind: opts.bind } : {}),
      skipAutoInit: true,
      idleShutdownHandler: (destroyServer) => {
        const handler = destroyServer;
        const reaped =
          reapDirOnIdle !== undefined ? withEphemeralTempDirReap(handler, reapDirOnIdle) : handler;
        return withIdleShutdownProcessExit(reaped, { log, exit: opts.idleExit });
      },
      log,
      ...(opts.serveContentAssets !== undefined
        ? { serveContentAssets: opts.serveContentAssets }
        : {}),
      ...(opts.reactShellDistDir ? { reactShellDistDir: opts.reactShellDistDir } : {}),
      ...(opts.terminalAuthAvailable === true ? { terminalAuthAvailable: true } : {}),
    });
  } catch (err) {
    await reapOwnedEphemeralDir();
    throw err;
  }

  const innerDestroy = booted.destroy;
  const destroy = ownsEphemeralProjectDir
    ? async (...args: Parameters<typeof innerDestroy>): Promise<void> => {
        try {
          await innerDestroy(...args);
        } finally {
          await reapOwnedEphemeralDir();
        }
      }
    : innerDestroy;

  return {
    httpServer: booted.httpServer,
    destroy,
    lockDir: booted.lockDir,
    contentDir,
    port: booted.port,
    ready: booted.ready,
    degraded: booted.degraded,
  };
}

type StartMode = 'browser' | 'app';

interface StartCommandOptions {
  port?: string | number;
  bind?: string[];
  openBrowser?: boolean;
  only?: OnlyModule;
  idleShutdown?: string;
  mode?: StartMode;
  serveContentAssets?: boolean;
  reactShellDistDir?: string;
  singleFile?: string;
  projectDir?: string;
  externalUrl?: string;
  terminalAuth?: boolean;
}

export function resolveStartConfig(
  config: Config,
  singleFile: string | undefined,
  readUserConfig: () => Config = () =>
    readConfigSafely({
      absPath: resolveConfigPath('user', process.cwd()),
      sideline: false,
      warn: () => {},
    }).value,
): Config {
  return singleFile !== undefined ? readUserConfig() : config;
}

function parseStartMode(value: string): StartMode {
  if (value === 'browser' || value === 'app') return value;
  throw new InvalidArgumentError("--mode must be 'browser' or 'app'");
}

export function resolveStartConsoleLevel(env: {
  OK_CONSOLE_LEVEL?: string | undefined;
  LOG_LEVEL?: string | undefined;
}): string | null {
  if (env.OK_CONSOLE_LEVEL !== undefined || env.LOG_LEVEL !== undefined) return null;
  return 'warn';
}

export function formatShutdownNotice(signal: NodeJS.Signals): string[] {
  const lines = [
    'Stopping OpenKnowledge…',
    'Saving pending changes and releasing the server lock — this can take a few seconds.',
  ];
  if (signal === 'SIGINT') {
    lines.push('Press Ctrl+C again to force quit.');
  }
  return lines;
}

export async function runStartCommand(configArg: Config, opts: StartCommandOptions): Promise<void> {
  const config = resolveStartConfig(configArg, opts.singleFile);
  const startConsoleLevel = resolveStartConsoleLevel(process.env);
  if (startConsoleLevel !== null) process.env.OK_CONSOLE_LEVEL = startConsoleLevel;

  const { renderBanner } = await import('../ui/banner.ts');
  const { accent, dim, error, warning } = await import('../ui/colors.ts');

  const cwd = process.cwd();

  process.title = deriveServerProcessTitle(cwd);

  let envLayer: EnvConfigLayer;
  try {
    envLayer = resolveEnvConfigLayer(process.env);
  } catch (err) {
    if (err instanceof EnvVarError) {
      console.error(error(err.message));
      process.exit(78);
    }
    throw err;
  }
  for (const diag of envLayer.diagnostics) {
    console.warn(warning(`[config] ${diag.message}`));
  }
  const envConfig = applyConfigOverlay(config, envLayer.layer) as Config;

  const okBindSet = envLayer.overrides.some((o) => o.envVar === 'OK_BIND');
  const flagBind = opts.bind !== undefined && opts.bind.length > 0 ? opts.bind : undefined;
  const hostEnvRaw = process.env.HOST;
  const hostEnv = hostEnvRaw !== undefined && hostEnvRaw.trim() !== '' ? hostEnvRaw : undefined;
  const envFileRuntime = resolveServerRuntimeConfig(envConfig);
  const requestedBind =
    flagBind ?? (okBindSet || hostEnv === undefined ? [...envFileRuntime.bind] : [hostEnv]);

  if (
    shouldWarnHostOverridesMultiBind({
      flagBindSet: flagBind !== undefined,
      okBindSet,
      hostEnvSet: hostEnv !== undefined,
      fileBindCount: envFileRuntime.bind.length,
    })
  ) {
    console.warn(
      warning(
        `[config] HOST=${hostEnv} overrides server.bind — dropping the file-configured addresses (${envFileRuntime.bind.join(', ')}). Use OK_BIND with a space-separated list to keep multiple binds.`,
      ),
    );
  }

  const host = requestedBind[0] ?? DEFAULT_SERVER_HOST;
  const bindList = requestedBind;
  const flagExternalUrl = opts.externalUrl;
  const runtime: ServerRuntimeConfig = resolveServerRuntimeConfig(
    applyConfigOverlay(envConfig, {
      server: {
        bind: bindList,
        ...(flagExternalUrl !== undefined ? { externalUrl: flagExternalUrl } : {}),
      },
    }) as Config,
  );

  if (runtime.allowExternal && (!runtime.loopbackOnly || runtime.externalUrl)) {
    const reach = runtime.externalUrl ?? runtime.bind.join(', ');
    console.warn(
      warning(
        [
          '',
          '⚠  EXTERNAL ACCESS ENABLED (server.allowExternal) — no server-side authentication.',
          `   This server is reachable beyond this machine (${reach}). Anyone who can`,
          '   reach it has FULL control of this knowledge base — sync, publishing, GitHub',
          '   credentials, and local operations (clone, sign-in, repo spawn).',
          '   Restrict who can reach it at the edge: a Tailscale ACL, a reverse proxy with',
          '   auth (Cloudflare Access, oauth2-proxy), or a firewall.',
          '',
        ].join('\n'),
      ),
    );
  }

  const portFromCli = opts.port !== undefined ? Number(opts.port) : undefined;
  const portFromEnv = envLayer.overrides.find((o) => o.envVar === 'PORT')?.value as
    | number
    | undefined;
  const port = portFromCli ?? portFromEnv ?? config.server?.port;

  const shell = resolveStartShellDir({
    explicitDir: opts.reactShellDistDir,
    only: opts.only,
    findBundledDir: resolveBundledReactShellDir,
  });
  const reactShellDistDir = shell.dir;
  if (shell.missingBundle) {
    console.warn(
      'bundled web UI not found — serving /api and /mcp only. Reinstall @inkeep/open-knowledge, or build packages/app in a source checkout.',
    );
  }

  let booted: BootedStartServer;
  try {
    booted = await bootStartServer({
      config,
      cwd,
      host,
      port,
      bind: bindList,
      ...(opts.serveContentAssets !== undefined
        ? { serveContentAssets: opts.serveContentAssets }
        : {}),
      ...(reactShellDistDir ? { reactShellDistDir } : {}),
      idleThresholdMs: idleShutdownToMs(opts.idleShutdown ?? runtime.idleShutdown),
      serverRuntime: runtime,
      ...(opts.singleFile ? { singleFile: opts.singleFile } : {}),
      ...(opts.projectDir ? { projectDir: opts.projectDir } : {}),
      ...(opts.terminalAuth === true ? { terminalAuthAvailable: true } : {}),
    });
  } catch (err) {
    if (err instanceof OkDirMissingError) {
      console.error(error(err.message));
      process.exit(1);
    }

    if (err instanceof EphemeralProjectDirNotThrowawayError) {
      console.error(error(err.message));
      process.exit(1);
    }

    const serverModule = await import('@inkeep/open-knowledge-server');
    if (
      err instanceof serverModule.GitNotAvailableError ||
      err instanceof serverModule.GitProbeTimeoutError ||
      err instanceof serverModule.GitTooOldError
    ) {
      process.exit(78);
    }

    if (err instanceof serverModule.ExposureConsentError) {
      console.error(error(err.message));
      process.exit(78);
    }

    if (
      err instanceof serverModule.SingleFileNotFoundError ||
      err instanceof serverModule.SingleFileNotAFileError ||
      err instanceof serverModule.SingleFileNotMarkdownError
    ) {
      console.error(error(err.message));
      process.exit(1);
    }

    if (
      err instanceof serverModule.MissingOkConfigError ||
      err instanceof serverModule.DocumentDurabilityStateError
    ) {
      console.error(error(err.message));
      process.exit(1);
    }

    if (isServerLockCollision(err, serverModule, cwd)) {
      const lockDir = serverModule.resolveLockDir(cwd);
      let reuse: ServerReuseInfo | null = null;
      try {
        reuse = await resolveServerReuse({
          readServerLock: () => serverModule.readServerLock(lockDir),
          now: Date.now,
          sleep: (ms) => wait(ms),
          timeoutMs: 3000,
          pollIntervalMs: 50,
        });
      } catch (reuseErr) {
        process.stderr.write(
          `[start] spawn-or-reuse: lock poll failed (${reuseErr instanceof Error ? reuseErr.message : String(reuseErr)}) — falling back to the collision message\n`,
        );
      }
      if (reuse !== null) {
        const [headline, ...rest] = formatServerReuseNotice(reuse);
        console.log(accent(headline));
        for (const line of rest) {
          console.log(dim(line));
        }
        process.exit(0);
      }
    }

    const tailored = tryDescribeLockCollision(err, cwd, serverModule);
    if (tailored !== null) {
      console.error(error(tailored));
      process.exit(1);
    }

    console.error(
      `${error('Failed to start:')} ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`,
    );
    process.exit(1);
  }

  let shuttingDown = false;
  const shutdown = async (signal: NodeJS.Signals) => {
    if (shuttingDown) return;
    shuttingDown = true;
    const [headline, ...details] = formatShutdownNotice(signal);
    console.log(accent(`\n${headline}`));
    for (const line of details) {
      console.log(dim(`  ${line}`));
    }
    try {
      await booted.destroy('external-signal', { signal });
    } catch (err) {
      console.error(
        `${error('destroy() failed:')} ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`,
      );
      process.exitCode = 1;
    }
    process.exit(process.exitCode ?? 0);
  };
  process.once('SIGINT', () => {
    void shutdown('SIGINT');
  });
  process.once('SIGTERM', () => {
    void shutdown('SIGTERM');
  });

  const urlHost = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
  const apiUrl = `http://${urlHost}:${booted.port}`;
  const networkUrl =
    host === '0.0.0.0' || host === '::' ? `http://0.0.0.0:${booted.port}` : undefined;

  const localUrl = apiUrl;

  console.log(
    renderBanner({
      name: 'open-knowledge',
      version: PACKAGE_VERSION,
      localUrl,
      networkUrl,
      nextSteps: ['Open the Editor URL in your browser to start editing.'],
    }),
  );
  const DEGRADED_IMPACTS: Record<string, string> = {
    'shadow-repo': 'Version history and branch-switch safety unavailable',
    'file-watcher': 'External file changes will not sync to the editor',
    'head-watcher': 'Git branch switches may cause document inconsistency',
  };
  booted.ready
    .then(async () => {
      if (booted.degraded.length > 0) {
        console.log();
        for (const id of booted.degraded) {
          const impact = DEGRADED_IMPACTS[id] ?? `${id} (check server logs for details)`;
          console.warn(`  ${warning('\u26a0')} ${warning(id)}: ${dim(impact)}`);
        }
        console.log();
      }

      const openDecision = shouldOpenBrowser({
        openBrowser: opts.openBrowser !== false && runtime.openBrowser,
        explicitOn: opts.openBrowser !== false && envConfig.server?.openBrowser === true,
        host,
        isTTY: process.stdout.isTTY === true,
        ephemeral: opts.singleFile !== undefined,
        only: opts.only,
        servesUi: reactShellDistDir !== undefined,
      });
      if (openDecision) {
        const { openBrowser } = await import('../utils/open-browser.ts');
        openBrowser(localUrl);
      }
    })
    .catch((err) => {
      console.error(
        `  ${error('Server initialization failed:')} ${err instanceof Error ? err.message : String(err)}`,
      );
    });
}

export interface ServerReuseInfo {
  url: string;
  kind?: string | undefined;
  pid: number;
  servesUi: boolean;
}

interface ResolveServerReuseDeps {
  readServerLock: () => {
    pid: number;
    port: number;
    url?: string;
    kind?: string;
    draining?: boolean;
    capabilities?: string[];
  } | null;
  now: () => number;
  sleep: (ms: number) => Promise<void>;
  timeoutMs: number;
  pollIntervalMs: number;
}

/**
 * All time + IO deps injected (precedent #13b) so tests drive every branch with a virtual clock and
 * no filesystem.
 */
export async function resolveServerReuse(
  deps: ResolveServerReuseDeps,
): Promise<ServerReuseInfo | null> {
  const deadline = deps.now() + deps.timeoutMs;
  let lock = deps.readServerLock();
  while (lock !== null && lock.draining !== true && lock.port <= 0 && deps.now() < deadline) {
    await deps.sleep(deps.pollIntervalMs);
    lock = deps.readServerLock();
  }
  if (lock === null || lock.draining === true || lock.port <= 0) return null;
  if (lockAdvertisesUi(lock) && lock.url !== undefined) {
    return { url: lock.url, kind: lock.kind, pid: lock.pid, servesUi: true };
  }
  return {
    url: lock.url ?? `http://${DEFAULT_SERVER_HOST}:${lock.port}`,
    kind: lock.kind,
    pid: lock.pid,
    servesUi: false,
  };
}

export function formatServerReuseNotice(info: ServerReuseInfo): string[] {
  const holder =
    info.kind === 'mcp-spawned'
      ? 'An MCP-spawned OpenKnowledge server is already running on this project'
      : 'OpenKnowledge is already running on this project';
  return [
    `${holder} (pid ${info.pid}).`,
    `  ${info.url}`,
    `Leaving it running — run \`${currentCliCommandName()} stop\` first if you want a fresh server.`,
  ];
}

export function isServerLockCollision(
  err: unknown,
  serverModule: typeof import('@inkeep/open-knowledge-server'),
  cwd: string,
): boolean {
  const lockErr = serverModule.ServerLockCollisionError;
  if (lockErr !== undefined && err instanceof lockErr) return true;
  const authorityErr = serverModule.ServerAuthorityCollisionError;
  if (authorityErr === undefined || !(err instanceof authorityErr)) return false;
  try {
    return (
      err.existing.scope.kind === 'tree' && realpathSync.native(cwd) === err.existing.projectDir
    );
  } catch {
    return false;
  }
}

export function tryDescribeLockCollision(
  err: unknown,
  cwd: string,
  serverModule: typeof import('@inkeep/open-knowledge-server'),
): string | null {
  const authorityErr = serverModule.ServerAuthorityCollisionError;
  if (authorityErr !== undefined && err instanceof authorityErr) return err.message;
  const registryErr = serverModule.ServerAuthorityRegistryError;
  if (registryErr !== undefined && err instanceof registryErr) return err.message;
  const lockFileErr = serverModule.ProcessLockFileError;
  if (lockFileErr !== undefined && err instanceof lockFileErr) return err.message;
  const lockErr = serverModule.ServerLockCollisionError;
  if (lockErr === undefined || !(err instanceof lockErr)) return null;

  try {
    const meta = serverModule.readServerLock(serverModule.resolveLockDir(cwd));
    const command = currentCliCommandName();
    if (meta?.kind === 'mcp-spawned') {
      return `An MCP-spawned server holds this lock; it should release on idle-shutdown (~30 min). Or run \`${command} stop\`.`;
    }
    return `OpenKnowledge server is already running on this project — check \`${command} status\` or \`${command} stop\`.`;
  } catch {
    return null;
  }
}

export function startCommand(getConfig: () => Config): Command {
  const cmd = new Command('start')
    .description('Start the OpenKnowledge server (UI + API + MCP + collab on one port)')
    .option('-p, --port <port>', 'Server port', undefined)
    .option(
      '--bind <address>',
      'Bind address (repeatable; default 127.0.0.1 — loopback only)',
      (value: string, prev: string[] | undefined) => [...(prev ?? []), value],
    )
    .option(
      '--no-open-browser',
      'Do not open the browser after start (interactive loopback starts open it by default)',
    )
    .option(
      '--only <module>',
      "Serve one module: 'server' (API + MCP only, no shell or browser)",
      parseOnlyModule,
    )
    .option(
      '--idle-shutdown <duration>',
      "Shut the server down after this long with no connected clients ('off', or a duration like 90s, 30m, 2h; default 30m)",
      parseIdleShutdownFlag,
    )
    .option('--mode <mode>', "Force dispatch mode: 'browser' or 'app'", parseStartMode)
    .option(
      '--serve-content-assets',
      'Serve content assets from this server (now the default; kept for compatibility)',
    )
    .option('--react-shell-dist-dir <path>', 'Serve React shell from <path>')
    .addOption(
      new Option(
        '--single-file <path>',
        'No-project ephemeral single-file mode: scope the server to one markdown file (git + MCP off)',
      ).hideHelp(),
    )
    .addOption(
      new Option(
        '--project-dir <dir>',
        'Throwaway project root for --single-file (where ephemeral .ok/ state lives)',
      ).hideHelp(),
    )
    .addOption(
      new Option(
        '--terminal-auth',
        "Tell in-app agents that this server's client can run terminal sign-ins (the desktop app passes it when it has a terminal)",
      ).hideHelp(),
    )
    .option(
      '--external-url <url>',
      'Canonical external origin clients dial (sets server.externalUrl for this run) — its host joins the Host/Origin allowlists (CORS + external-Host admission). External exposure additionally requires consent (OK_ALLOW_EXTERNAL=1 or server.allowExternal).',
      parseExternalUrlFlag,
    )
    .action(async (opts: StartCommandOptions) => {
      const config = getConfig();

      if (opts.only === 'server' && opts.reactShellDistDir !== undefined) {
        process.stderr.write(
          "error: option '--only server' cannot be combined with '--react-shell-dist-dir'\n",
        );
        process.exit(2);
      }

      if (opts.projectDir !== undefined && opts.singleFile === undefined) {
        process.stderr.write("error: option '--project-dir' requires '--single-file'\n");
        process.exit(2);
      }

      if (opts.mode === 'app') {
        const ignored: string[] = [];
        if (opts.port !== undefined) ignored.push('--port');
        if (opts.bind !== undefined) ignored.push('--bind');
        if (opts.only !== undefined) ignored.push('--only');
        if (opts.idleShutdown !== undefined) ignored.push('--idle-shutdown');
        if (opts.openBrowser === false) ignored.push('--no-open-browser');
        if (opts.externalUrl !== undefined) ignored.push('--external-url');
        if (ignored.length > 0) {
          const logLevel = process.env.OK_LOG_LEVEL ?? 'info';
          if (logLevel === 'debug' || logLevel === 'trace') {
            console.error(`--mode=app: ignoring ${ignored.join(', ')}`);
          }
        }

        const decision = detectDesktop(createRealDetectDeps());

        if (decision.available) {
          launchDesktop({ spawn: nativeSpawn }, decision);
          return;
        }

        console.error(notFoundMessage(decision.reason));
        process.exit(1);
      }

      await runStartCommand(config, opts);
    });

  return cmd;
}