user-docs

/**
 * Debug logger for the RAG subsystem.
 * Disabled by default; enable with USER_DOCS_RAG_DEBUG=1.
 */

import fs from "fs";
import path from "path";

function logsDir(): string {
  return path.join(process.cwd(), "logs");
}

function logFile(): string {
  return path.join(logsDir(), "rag.log");
}

function ts(): string {
  return new Date().toLocaleString(undefined, {
    year: "numeric",
    month: "2-digit",
    day: "2-digit",
    hour: "2-digit",
    minute: "2-digit",
    second: "2-digit",
    hour12: false,
    timeZoneName: "short",
  });
}

export function ragLog(tag: string, message: string): void {
  if (!isRagDebugEnabled()) return;
  const line = `${ts()} [${tag}] ${message}\n`;
  console.log(`[${tag}] ${message}`);
  try {
    fs.mkdirSync(logsDir(), { recursive: true });
    fs.appendFileSync(logFile(), line);
  } catch {
    // non-fatal
  }
}

export function ragDebug(tag: string, message: string): void {
  ragLog(tag, message);
}

export function isRagDebugEnabled(): boolean {
  const value = process.env.USER_DOCS_RAG_DEBUG?.trim().toLowerCase();
  return value === "1" || value === "true" || value === "yes";
}