Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

20.2 KB
Raw Blame
import { resolve } from 'node:path';
import {
  CHECKOUT_CLI_COMMAND,
  currentCliCommandName,
  DEV_CHANNEL,
  desktopChannelLabel,
  resolveDesktopProductName,
} from '@inkeep/open-knowledge-core';
import {
  assessLockHolder,
  type Config,
  isProcessAlive,
  lockBaseUrl,
  type ProcessLockMetadata,
  type ProcessStart,
  type ProcessStartCause,
  resolveLockDir,
  type UnverifiedLockHolderCause,
} from '@inkeep/open-knowledge-server';
import { Command } from 'commander';
import type { Logger as PinoLoggerInstance } from 'pino';
import { getCliLogger } from '../cli-logger.ts';
import { getInvocationCwd } from '../project-anchor.ts';
import { escapeDisplayPath } from '../utils/escape-display-path.ts';
import { discoverLockDirs } from '../utils/process-scan.ts';
import {
  describeHolderStartReadFailure,
  type HolderProcessStartOptions,
  type NativeFailure,
  readHolderProcessStart,
} from './holder-process-start.ts';
import {
  describeForeignOwner,
  describeOtherHomeFolderRemedy,
  describeUnrecordedOwner,
  inspectLock,
  type LockState,
} from './lock-state.ts';
import { runPs } from './ps.ts';

const CLIENT_PROBE_TIMEOUT_MS = 1500;

export async function probeCollabClients(
  lockDir: string,
  logger: PinoLoggerInstance | undefined = getCliLogger(),
): Promise<number | null> {
  const state = inspectLock(lockDir, 'server');
  if (state.status !== 'alive' && state.status !== 'foreign-host') return null;
  const baseUrl = lockBaseUrl(state.lock);
  if (baseUrl === null) return null;
  try {
    const res = await fetch(`${baseUrl}/api/server-info`, {
      signal: AbortSignal.timeout(CLIENT_PROBE_TIMEOUT_MS),
      redirect: 'manual',
    });
    if (!res.ok) {
      logger?.warn(
        { lockDir, baseUrl, outcome: 'http-error', status: res.status },
        'stop client-probe failed',
      );
      return null;
    }
    const body: unknown = await res.json();
    const count = (body as { collabClients?: unknown } | null)?.collabClients;
    if (typeof count === 'number' && Number.isFinite(count)) return count;
    logger?.warn(
      { lockDir, baseUrl, outcome: 'no-client-count', received: typeof count },
      'stop client-probe failed',
    );
    return null;
  } catch (err) {
    logger?.warn(
      {
        lockDir,
        baseUrl,
        outcome: 'unreachable',
        err,
      },
      'stop client-probe failed',
    );
    return null;
  }
}

interface StopTarget {
  name: 'server';
  pid: number;
}

interface StopTargetPlan extends StopTarget {
  port: number;
}

interface StopPlan {
  targets: StopTargetPlan[];
  lock?: ProcessLockMetadata;
}

interface BuildStopPlanDeps {
  isAlive?: (pid: number) => boolean;
}

export function buildStopPlan(server: LockState, deps: BuildStopPlanDeps = {}): StopPlan {
  const isAlive = deps.isAlive ?? isProcessAlive;
  if (!isStoppableState(server, isAlive)) return { targets: [] };
  return {
    targets: [{ name: 'server', pid: server.lock.pid, port: server.lock.port }],
    lock: server.lock,
  };
}

interface RunStopDeps {
  lockDir: string;
  force?: boolean;
  inspect?: () => LockState;
  kill?: (pid: number, signal: NodeJS.Signals) => void;
  isAlive?: (pid: number) => boolean;
  readProcessStart?: (pid: number, options?: HolderProcessStartOptions) => ProcessStart | null;
  log?: (msg: string) => void;
  error?: (msg: string) => void;
  probeClients?: (lockDir: string, logger?: PinoLoggerInstance) => Promise<number | null>;
  logger?: PinoLoggerInstance;
  selfChannel?: 'stable' | 'beta' | 'dev';
  platform?: NodeJS.Platform;
  readBootInstant?: () => number | null;
  refuseHolderStartedAfterLock?: boolean;
}

interface UnconfirmedStartHolder {
  readonly cause: ProcessStartCause;
  readonly pid: number;
  readonly lockPath: string;
  readonly platform: NodeJS.Platform;
  readonly nativeFailures: readonly NativeFailure[];
}

type UnverifiedHolder =
  | UnconfirmedStartHolder
  | {
      readonly cause: 'foreign-host';
      readonly pid: number;
      readonly lockPath: string;
      readonly lock: ProcessLockMetadata;
      readonly platform: NodeJS.Platform;
    }
  | { readonly cause: 'unverified-owner'; readonly pid: number; readonly lockPath: string };

interface StopFailure {
  target: StopTarget;
  error: string;
  unverified?: UnverifiedHolder;
}

interface StopOutcome {
  stopped: StopTargetPlan[];
  failed: StopFailure[];
  hadTargets: boolean;
  declined?: { clients: number } | { otherChannel: string };
}

function currentChannel(logger: PinoLoggerInstance | undefined): RunStopDeps['selfChannel'] {
  try {
    return resolveDesktopProductName();
  } catch (err) {
    logger?.warn(
      { err },
      `stop channel check skipped: ${err instanceof Error ? err.message : String(err)}`,
    );
    return undefined;
  }
}

export async function runStop(deps: RunStopDeps): Promise<StopOutcome> {
  const inspect = deps.inspect ?? (() => inspectLock(deps.lockDir, 'server'));
  const kill = deps.kill ?? ((pid, signal) => process.kill(pid, signal));
  const log = deps.log ?? ((msg) => console.log(msg));
  const error = deps.error ?? ((msg) => console.error(msg));
  const probeClients = deps.probeClients ?? probeCollabClients;
  const logger = deps.logger ?? getCliLogger();
  const platform = deps.platform ?? process.platform;

  const serverState = inspect();
  const plan = buildStopPlan(serverState, { isAlive: deps.isAlive });
  const { lock } = plan;
  const stopped: StopTargetPlan[] = [];
  const failed: StopFailure[] = [];
  const refuse = (target: StopTarget, holder: UnverifiedHolder): void => {
    logger?.warn(
      {
        lockDir: deps.lockDir,
        lockPath: holder.lockPath,
        lockPid: holder.pid,
        platform,
        cause: holder.cause,
        ...('nativeFailures' in holder && holder.nativeFailures.length > 0
          ? { nativeFailures: holder.nativeFailures }
          : {}),
      },
      'stop declined: lock holder identity unverified',
    );
    failed.push({
      target,
      error: describeUnverifiedHolderForStop(holder, logger !== undefined),
      unverified: holder,
    });
  };
  const report = (): StopOutcome => {
    if (stopped.length > 0) {
      const rendered = stopped.map((t) => `${t.name} (pid=${t.pid}, port=${t.port})`).join(', ');
      log(`Stopped: ${rendered}`);
    }
    logger?.info(
      {
        lockDir: deps.lockDir,
        signalled: stopped.map((t) => ({ name: t.name, pid: t.pid, port: t.port })),
        failed: failed.map(({ target, error: msg }) => ({ pid: target.pid, error: msg })),
        forced: deps.force === true,
      },
      'stop signalled processes',
    );
    if (failed.length > 0) {
      const rendered = failed
        .map(({ target, error: msg }) => `${target.name} (pid=${target.pid}): ${msg}`)
        .join('; ');
      error(`Failed to stop: ${rendered}`);
    }
    return { stopped, failed, hadTargets: true };
  };

  if (serverState.status === 'unverified-owner') {
    const { pid, lockPath } = serverState;
    refuse({ name: 'server', pid }, { cause: 'unverified-owner', pid, lockPath });
    return report();
  }

  if (lock === undefined) {
    log('No running open-knowledge processes.');
    logger?.info({ lockDir: deps.lockDir, targets: 0 }, 'stop found nothing to signal');
    return { stopped: [], failed: [], hadTargets: false };
  }

  const holder =
    serverState.status === 'alive' || serverState.status === 'foreign-host'
      ? serverState.lock.channel
      : undefined;
  if (deps.force !== true && typeof holder === 'string' && holder.length > 0) {
    const self = deps.selfChannel ?? currentChannel(logger);
    if (self !== undefined && holder !== self) {
      error(
        `Not stopping: the server at ${deps.lockDir} belongs to ${desktopChannelLabel(holder)}. ` +
          (holder === DEV_CHANNEL
            ? `Stop it from that dev build, or run \`${CHECKOUT_CLI_COMMAND} stop\` with OK_CHANNEL=dev set, or re-run with --force to terminate anyway.`
            : 'Stop it from that app or its CLI, or re-run with --force to terminate anyway.'),
      );
      logger?.warn(
        {
          lockDir: deps.lockDir,
          holderChannel: holder,
          selfChannel: self,
          pids: plan.targets.map((t) => t.pid),
        },
        'stop declined: server belongs to another channel',
      );
      return { stopped: [], failed: [], hadTargets: true, declined: { otherChannel: holder } };
    }
  }

  if (deps.force !== true) {
    const clients = await probeClients(deps.lockDir, logger);
    if (clients !== null && clients > 0) {
      error(
        `Not stopping: ${clients} collaboration client${clients === 1 ? '' : 's'} ` +
          `(editor window${clients === 1 ? '' : 's'} or agents) still connected to the server at ${deps.lockDir}. ` +
          'Close them, or re-run with --force to terminate anyway.',
      );
      logger?.warn(
        { lockDir: deps.lockDir, clients, pids: plan.targets.map((t) => t.pid) },
        'stop declined: live collaboration clients',
      );
      return { stopped: [], failed: [], hadTargets: true, declined: { clients } };
    }
  }

  for (const target of plan.targets) {
    const nativeFailures: NativeFailure[] = [];
    const holderStart = (deps.readProcessStart ?? readHolderProcessStart)(target.pid, {
      platform,
      onNativeFailure: (failure) => {
        nativeFailures.push(failure);
      },
    });
    const assessment = assessLockHolder(lock, {
      isAlive: deps.isAlive ?? isProcessAlive,
      readProcessStart: () => holderStart,
      refuseHolderStartedAfterLock: deps.refuseHolderStartedAfterLock,
      platform,
      readBootInstant: deps.readBootInstant,
    });
    switch (assessment.verdict) {
      case 'writer':
        try {
          kill(target.pid, 'SIGTERM');
          stopped.push(target);
        } catch (err) {
          failed.push({ target, error: err instanceof Error ? err.message : String(err) });
        }
        break;
      case 'gone':
        log(`${target.name} (pid=${target.pid}) had already exited`);
        break;
      case 'replaced':
        error(
          `Process ${target.pid} is no longer the server that wrote ${serverState.lockPath}; it was not signalled. ` +
            `Run \`${currentCliCommandName()} clean\` to remove the stale lock.`,
        );
        break;
      case 'unverified':
        refuse(
          target,
          unverifiedHolder(assessment.cause, {
            pid: target.pid,
            lockPath: serverState.lockPath,
            lock,
            platform,
            nativeFailures,
          }),
        );
        break;
      default: {
        const exhaustive: never = assessment;
        return exhaustive;
      }
    }
  }

  return report();
}

function unverifiedHolder(
  cause: UnverifiedLockHolderCause,
  found: {
    pid: number;
    lockPath: string;
    lock: ProcessLockMetadata;
    platform: NodeJS.Platform;
    nativeFailures: readonly NativeFailure[];
  },
): UnverifiedHolder {
  const { pid, lockPath } = found;
  switch (cause) {
    case 'foreign-host':
      return { cause, pid, lockPath, lock: found.lock, platform: found.platform };
    case 'unverified-owner':
      return { cause, pid, lockPath };
    default:
      return {
        cause,
        pid,
        lockPath,
        platform: found.platform,
        nativeFailures: found.nativeFailures,
      };
  }
}

const STOP_NOT_SIGNALLED = 'it was not signalled, and --force does not override this check.';

function describeUnverifiedHolderForStop(holder: UnverifiedHolder, causeRecorded: boolean): string {
  const { pid, lockPath } = holder;
  switch (holder.cause) {
    case 'foreign-host': {
      const { lock } = holder;
      if (typeof lock.machineId !== 'string') {
        return (
          `The server lock at ${lockPath} ${describeForeignOwner(lock)}, and the start of process ${pid}, which is running on this machine, does not confirm it as the server that wrote the lock; ` +
          `${STOP_NOT_SIGNALLED} If ${escapeDisplayPath(lock.hostname)} is another machine, stop the server there. ` +
          `If it is an earlier name of this machine, confirm that process ${pid} is an OpenKnowledge server before ending it yourself, and once no OpenKnowledge server is running for this project, remove ${lockPath}.`
        );
      }
      return (
        `The server lock at ${lockPath} ${describeForeignOwner(lock)}, so process ${pid}, which is running on this machine, cannot be confirmed as the server that wrote it; ` +
        `${STOP_NOT_SIGNALLED} ${describeOtherHomeFolderRemedy(lock, holder.platform)}`
      );
    }
    case 'unverified-owner':
      return (
        `The server lock at ${lockPath} ${describeUnrecordedOwner(pid)}, so it cannot be confirmed as the server that wrote the lock; ` +
        `${STOP_NOT_SIGNALLED} Check whether process ${pid} is an OpenKnowledge server, and if it is, stop it yourself. ` +
        'Do not remove the lock file while that process is running.'
      );
    default: {
      const refusal = describeUnconfirmedHolderStart(
        holder,
        STOP_NOT_SIGNALLED,
        `Once you have confirmed no OpenKnowledge server is running for this project, remove ${lockPath}.`,
        causeRecorded,
      );
      if (holder.cause !== 'writer-identity-unrecorded') return refusal;
      return `${refusal} A server you start again with this release records its machine ID, so \`${currentCliCommandName()} stop\` can confirm it.`;
    }
  }
}

export function describeUnconfirmedHolderStart(
  holder: UnconfirmedStartHolder,
  notSignalled: string,
  afterManualStop: string,
  causeRecorded: boolean,
): string {
  const { pid, lockPath, platform, nativeFailures } = holder;
  const confirmFirst = `Before ending process ${pid} yourself, confirm that it is an OpenKnowledge server.`;
  switch (holder.cause) {
    case 'process-start-unreadable':
      return (
        `Could not read when process ${pid} started, so it cannot be confirmed as the server that wrote ${lockPath}; ` +
        `${notSignalled} ` +
        describeHolderStartReadFailure({ platform, pid, nativeFailures, causeRecorded }) +
        `${confirmFirst} ${afterManualStop}`
      );
    case 'process-start-incomparable':
      return (
        `The start of process ${pid} cannot be compared with the start recorded in ${lockPath}, so it cannot be confirmed as the server that wrote the lock; ` +
        `${notSignalled} ${confirmFirst} ${afterManualStop}`
      );
    case 'process-start-mismatch':
      return (
        `Process ${pid} started before the start recorded in ${lockPath}, so it cannot be confirmed as the server that wrote the lock; ` +
        `${notSignalled} ${confirmFirst} ${afterManualStop}`
      );
    case 'process-started-after-lock':
      return (
        `Process ${pid} started after the server lock at ${lockPath} was written, so it cannot be confirmed as the server that wrote the lock; ` +
        `${notSignalled} ${confirmFirst} ${afterManualStop}`
      );
    case 'recorded-start-in-future':
      return (
        `The server lock at ${lockPath} records a start later than the current time on this machine, so process ${pid} cannot be confirmed as the server that wrote it; ` +
        `${notSignalled} ${confirmFirst} ${afterManualStop}`
      );
    case 'writer-identity-unrecorded':
      return (
        `The server lock at ${lockPath} records neither a machine ID nor a process start, as locks written by version 0.25.0 and earlier do, so process ${pid} cannot be confirmed as the server that wrote it; ` +
        `${notSignalled} ${confirmFirst} ${afterManualStop}`
      );
    default: {
      const exhaustive: never = holder.cause;
      return exhaustive;
    }
  }
}

function isStoppableState(
  state: LockState,
  isAlive: (pid: number) => boolean,
): state is Extract<LockState, { status: 'alive' | 'foreign-host' }> {
  if (state.status === 'alive') return true;
  if (state.status === 'foreign-host') return isAlive(state.lock.pid);
  return false;
}

async function findLockDirByNumber(
  n: number,
  isAlive: (pid: number) => boolean = isProcessAlive,
): Promise<string | null> {
  const lockDirs = await discoverLockDirs();
  let pidMatch: string | null = null;
  for (const lockDir of lockDirs) {
    const server = inspectLock(lockDir, 'server');
    if (!isStoppableState(server, isAlive)) continue;
    if (server.lock.port === n) return lockDir;
    if (pidMatch === null && server.lock.pid === n) pidMatch = lockDir;
  }
  return pidMatch;
}

function setExitCodeForStop(outcome: StopOutcome): void {
  if (outcome.failed.length > 0 || outcome.declined !== undefined) process.exitCode = 1;
}

async function executeStop(lockDir: string, force: boolean): Promise<StopOutcome> {
  const outcome = await runStop({ lockDir, force });
  setExitCodeForStop(outcome);
  return outcome;
}

export function formatNoTargetMessage(
  targetDir: string,
  otherRunningServers: number,
  opts: {
    listingFollows?: boolean;
  } = {},
): string {
  if (otherRunningServers === 0) {
    return `Nothing was running for ${targetDir}, and no other open-knowledge servers are running.`;
  }
  const agreement = otherRunningServers === 1 ? ' is' : 's are';
  const pointer =
    opts.listingFollows === true ? '' : ` — run \`${currentCliCommandName()} ps\` to list them`;
  return (
    `Nothing was running for ${targetDir}. ${otherRunningServers} other open-knowledge server` +
    `${agreement} running${pointer}.`
  );
}

async function countOtherRunningServers(exceptLockDir: string): Promise<number> {
  const lockDirs = await discoverLockDirs();
  let count = 0;
  for (const lockDir of lockDirs) {
    if (lockDir === exceptLockDir) continue;
    if (isStoppableState(inspectLock(lockDir, 'server'), isProcessAlive)) {
      count++;
    }
  }
  return count;
}

export function stopCommand(getConfig: () => Config): Command {
  return new Command('stop')
    .description(
      'Stop open-knowledge server(s). With no argument: stops the server for the enclosing project — run it from anywhere inside the project. ' +
        'Pass a port number, a directory path, or "all" to target globally.',
    )
    .argument('[target...]', 'port number, directory path (spaces OK), or "all"')
    .option(
      '--force',
      'Stop even when the server belongs to another OpenKnowledge app (Stable, Beta or a dev build run from source) or editor windows or agents are still connected to it',
    )
    .action(async (parts: string[], options: { force?: boolean }) => {
      const force = options.force === true;
      const target = parts.length === 0 ? undefined : parts.join(' ');

      if (target === undefined) {
        getConfig();
        const lockDir = resolveLockDir(process.cwd());
        const buffered: string[] = [];
        const outcome = await runStop({ lockDir, force, log: (msg) => buffered.push(msg) });
        if (outcome.hadTargets) {
          for (const line of buffered) console.log(line);
          setExitCodeForStop(outcome);
        } else {
          const others = await countOtherRunningServers(lockDir);
          console.log(formatNoTargetMessage(process.cwd(), others, { listingFollows: others > 0 }));
          if (others > 0) await runPs({});
        }
        return;
      }

      if (target === 'all') {
        const lockDirs = await discoverLockDirs();
        if (lockDirs.length === 0) {
          console.log('No running open-knowledge servers found.');
          return;
        }
        let stopped = 0;
        for (const lockDir of lockDirs) {
          if (!isStoppableState(inspectLock(lockDir, 'server'), isProcessAlive)) continue;
          await executeStop(lockDir, force);
          stopped++;
        }
        if (stopped === 0) console.log('No running open-knowledge servers found.');
        return;
      }

      if (/^\d+$/.test(target)) {
        const n = Number.parseInt(target, 10);
        const lockDir = await findLockDirByNumber(n);
        if (lockDir === null) {
          console.log(`No running open-knowledge server found with port or PID ${n}.`);
          return;
        }
        await executeStop(lockDir, force);
        return;
      }

      const targetDir = resolve(getInvocationCwd(), target);
      const lockDir = resolveLockDir(targetDir);
      const buffered: string[] = [];
      const outcome = await runStop({ lockDir, force, log: (msg) => buffered.push(msg) });
      setExitCodeForStop(outcome);
      if (outcome.hadTargets) {
        for (const line of buffered) console.log(line);
      } else {
        console.log(formatNoTargetMessage(targetDir, await countOtherRunningServers(lockDir)));
      }
    });
}