feat: implement embedding tracker controller with lazy and eager modes, enhance process lifecycle management, and add related tests

Author: ForLoopCodes

package-lock.json

@@ -11,6 +11,17 @@ export interface EmbeddingTrackerOptions {
   maxFilesPerTick?: number;
 }
 
+export interface EmbeddingTrackerController {
+  ensureStarted: () => void;
+  stop: () => void;
+  isRunning: () => boolean;
+}
+
+export interface EmbeddingTrackerControllerOptions extends EmbeddingTrackerOptions {
+  mode?: string;
+  starter?: (options: EmbeddingTrackerOptions) => () => void;
+}
+
 const MIN_FILES_PER_TICK = 5;
 const MAX_FILES_PER_TICK = 10;
 const DEFAULT_FILES_PER_TICK = 8;
@@ -44,6 +55,14 @@ function clampDebounceMs(value: number | undefined): number {
   return Math.max(100, Math.floor(value ?? DEFAULT_DEBOUNCE_MS));
 }
 
+export function parseEmbeddingTrackerMode(value: string | undefined): "off" | "lazy" | "eager" {
+  if (!value) return "lazy";
+  const normalized = value.trim().toLowerCase();
+  if (["false", "0", "no", "off", "disabled", "none"].includes(normalized)) return "off";
+  if (["eager", "startup", "boot"].includes(normalized)) return "eager";
+  return "lazy";
+}
+
 export function startEmbeddingTracker(options: EmbeddingTrackerOptions): () => void {
   const pendingFiles = new Set<string>();
   const debounceMs = clampDebounceMs(options.debounceMs);
@@ -111,3 +130,31 @@ export function startEmbeddingTracker(options: EmbeddingTrackerOptions): () => v
     watcher = null;
   };
 }
+
+export function createEmbeddingTrackerController(options: EmbeddingTrackerControllerOptions): EmbeddingTrackerController {
+  const { mode: rawMode, starter = startEmbeddingTracker, ...trackerOptions } = options;
+  const mode = parseEmbeddingTrackerMode(rawMode);
+
+  let running = false;
+  let stopTracker = () => { };
+
+  const ensureStarted = (): void => {
+    if (running || mode === "off") return;
+    stopTracker = starter(trackerOptions);
+    running = true;
+  };
+
+  if (mode === "eager") ensureStarted();
+
+  return {
+    ensureStarted,
+    stop: () => {
+      if (!running) return;
+      running = false;
+      const stop = stopTracker;
+      stopTracker = () => { };
+      stop();
+    },
+    isRunning: () => running,
+  };
+}

src/core/embedding-tracker.ts

@@ -6,11 +6,43 @@ interface ErrorWithCode {
 }
 
 const BROKEN_PIPE_CODES = new Set(["EPIPE", "ERR_STREAM_DESTROYED", "ECONNRESET"]);
+const DEFAULT_IDLE_TIMEOUT_MS = 15 * 60 * 1000;
+const MIN_IDLE_TIMEOUT_MS = 60 * 1000;
+const DEFAULT_PARENT_POLL_MS = 5 * 1000;
+const MIN_PARENT_POLL_MS = 1 * 1000;
 
 export interface CleanupOptions {
   stopTracker: () => void;
   closeServer: () => Promise<void> | void;
   closeTransport: () => Promise<void> | void;
+  stopMonitors?: () => void;
+}
+
+export interface IdleMonitor {
+  touch: () => void;
+  stop: () => void;
+}
+
+export interface IdleMonitorOptions {
+  timeoutMs: number;
+  onIdle: () => void;
+}
+
+export interface ParentMonitorOptions {
+  parentPid: number;
+  pollIntervalMs?: number;
+  onParentExit: () => void;
+  isProcessAlive?: (pid: number) => boolean;
+}
+
+function toIntegerOr(value: string | undefined, fallback: number): number {
+  if (!value) return fallback;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function unrefHandle(handle: { unref?: () => void } | null): void {
+  handle?.unref?.();
 }
 
 export function isBrokenPipeError(error: unknown): boolean {
@@ -19,7 +51,89 @@ export function isBrokenPipeError(error: unknown): boolean {
   return typeof code === "string" && BROKEN_PIPE_CODES.has(code);
 }
 
+export function getIdleShutdownMs(value: string | undefined): number {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized && ["0", "false", "off", "disabled", "none"].includes(normalized)) return 0;
+  return Math.max(MIN_IDLE_TIMEOUT_MS, toIntegerOr(value, DEFAULT_IDLE_TIMEOUT_MS));
+}
+
+export function getParentPollMs(value: string | undefined): number {
+  return Math.max(MIN_PARENT_POLL_MS, toIntegerOr(value, DEFAULT_PARENT_POLL_MS));
+}
+
+export function isProcessAlive(pid: number, killCheck: (pid: number, signal: number) => void = process.kill): boolean {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+
+  try {
+    killCheck(pid, 0);
+    return true;
+  } catch (error) {
+    if (!error || typeof error !== "object") return false;
+    const { code } = error as ErrorWithCode;
+    return code !== "ESRCH";
+  }
+}
+
+export function createIdleMonitor(options: IdleMonitorOptions): IdleMonitor {
+  if (options.timeoutMs <= 0) {
+    return {
+      touch: () => { },
+      stop: () => { },
+    };
+  }
+
+  let timer: NodeJS.Timeout | null = null;
+
+  const schedule = (): void => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      options.onIdle();
+    }, options.timeoutMs);
+    unrefHandle(timer);
+  };
+
+  schedule();
+
+  return {
+    touch: schedule,
+    stop: () => {
+      if (!timer) return;
+      clearTimeout(timer);
+      timer = null;
+    },
+  };
+}
+
+export function startParentMonitor(options: ParentMonitorOptions): () => void {
+  if (!Number.isFinite(options.parentPid) || options.parentPid <= 1 || options.parentPid === process.pid) {
+    return () => { };
+  }
+
+  const pollIntervalMs = Math.max(MIN_PARENT_POLL_MS, Math.floor(options.pollIntervalMs ?? DEFAULT_PARENT_POLL_MS));
+  const isAlive = options.isProcessAlive ?? isProcessAlive;
+  let stopped = false;
+
+  const stop = (): void => {
+    if (stopped) return;
+    stopped = true;
+    clearInterval(interval);
+  };
+
+  const interval = setInterval(() => {
+    if (stopped) return;
+    if (process.ppid !== options.parentPid || !isAlive(options.parentPid)) {
+      stop();
+      options.onParentExit();
+    }
+  }, pollIntervalMs);
+
+  unrefHandle(interval);
+  return stop;
+}
+
 export async function runCleanup(options: CleanupOptions): Promise<void> {
+  options.stopMonitors?.();
   options.stopTracker();
   await Promise.allSettled([
     Promise.resolve(options.closeServer()),