@lincoln504/pi-research 0.0.0

package/src/utils/research-error.ts

@@ -0,0 +1,205 @@
+/**
+ * Research Error Handling
+ *
+ * Custom error class and error codes for research operations.
+ */
+
+import { logger } from '../logger.ts';
+
+/**
+ * Research error codes
+ */
+export enum ResearchErrorCode {
+  // General errors
+  UNKNOWN = 'UNKNOWN',
+  INVALID_INPUT = 'INVALID_INPUT',
+  NOT_IMPLEMENTED = 'NOT_IMPLEMENTED',
+
+  // Configuration errors
+  CONFIG_INVALID = 'CONFIG_INVALID',
+  CONFIG_MISSING = 'CONFIG_MISSING',
+
+  // Network/API errors
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  API_ERROR = 'API_ERROR',
+  API_RATE_LIMITED = 'API_RATE_LIMITED',
+  API_TIMEOUT = 'API_TIMEOUT',
+  API_UNAVAILABLE = 'API_UNAVAILABLE',
+
+  // SearXNG errors
+  SEARXNG_START_FAILED = 'SEARXNG_START_FAILED',
+  SEARXNG_NOT_RUNNING = 'SEARXNG_NOT_RUNNING',
+  SEARXNG_QUERY_FAILED = 'SEARXNG_QUERY_FAILED',
+
+  // Orchestrator errors
+  ORCHESTRATION_FAILED = 'ORCHESTRATION_FAILED',
+  PLANNING_FAILED = 'PLANNING_FAILED',
+  RESEARCH_FAILED = 'RESEARCH_FAILED',
+  SYNTHESIS_FAILED = 'SYNTHESIS_FAILED',
+
+  // Researcher errors
+  RESEARCHER_FAILED = 'RESEARCHER_FAILED',
+  RESEARCHER_TIMEOUT = 'RESEARCHER_TIMEOUT',
+
+  // Scraping errors
+  SCRAPE_FAILED = 'SCRAPE_FAILED',
+  SCRAPE_TIMEOUT = 'SCRAPE_TIMEOUT',
+  SCRAPE_RATE_LIMITED = 'SCRAPE_RATE_LIMITED',
+
+  // Export errors
+  EXPORT_FAILED = 'EXPORT_FAILED',
+
+  // Validation errors
+  VALIDATION_FAILED = 'VALIDATION_FAILED',
+  QUERY_TOO_SHORT = 'QUERY_TOO_SHORT',
+  QUERY_TOO_LONG = 'QUERY_TOO_LONG',
+  QUERY_INVALID = 'QUERY_INVALID',
+
+  // State errors
+  STATE_INVALID = 'STATE_INVALID',
+  STATE_TRANSITION_FAILED = 'STATE_TRANSITION_FAILED',
+}
+
+/**
+ * Research error class
+ *
+ * Provides structured error information for research operations.
+ */
+export class ResearchError extends Error {
+  public readonly code: ResearchErrorCode;
+  public readonly details?: unknown;
+  public readonly correlationId: string;
+  public readonly timestamp: number;
+
+  constructor(
+    code: ResearchErrorCode,
+    message: string,
+    details?: unknown,
+  ) {
+    super(message);
+    this.name = 'ResearchError';
+    this.code = code;
+    this.details = details;
+    this.correlationId = generateCorrelationId();
+    this.timestamp = Date.now();
+
+    // Ensure proper prototype chain
+    Object.setPrototypeOf(this, ResearchError.prototype);
+  }
+
+  /**
+   * Convert error to a serializable object
+   */
+  toJSON(): {
+    name: string;
+    code: ResearchErrorCode;
+    message: string;
+    details?: unknown;
+    correlationId: string;
+    timestamp: number;
+  } {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      details: this.details,
+      correlationId: this.correlationId,
+      timestamp: this.timestamp,
+    };
+  }
+
+  /**
+   * Log the error with correlation ID
+   */
+  log(context?: string): void {
+    const prefix = context ? `[${context}] ` : '';
+    logger.error(`${prefix}ResearchError: ${this.code}`, {
+      message: this.message,
+      details: this.details,
+      correlationId: this.correlationId,
+      timestamp: this.timestamp,
+    });
+  }
+}
+
+/**
+ * Generate a correlation ID for error tracking
+ */
+function generateCorrelationId(): string {
+  return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+}
+
+/**
+ * Create a ResearchError from an unknown error
+ *
+ * @param error - The error to convert
+ * @param defaultCode - Default error code if type cannot be determined
+ * @returns A ResearchError instance
+ */
+export function createResearchError(
+  error: unknown,
+  defaultCode: ResearchErrorCode = ResearchErrorCode.UNKNOWN,
+): ResearchError {
+  if (error instanceof ResearchError) {
+    return error;
+  }
+
+  if (error instanceof Error) {
+    // Try to determine error code from error message
+    const message = error.message.toLowerCase();
+
+    if (message.includes('timeout')) {
+      return new ResearchError(ResearchErrorCode.API_TIMEOUT, error.message, error);
+    }
+
+    if (message.includes('rate limit') || message.includes('too many requests')) {
+      return new ResearchError(ResearchErrorCode.API_RATE_LIMITED, error.message, error);
+    }
+
+    if (message.includes('network') || message.includes('econnrefused')) {
+      return new ResearchError(ResearchErrorCode.NETWORK_ERROR, error.message, error);
+    }
+
+    if (message.includes('404') || message.includes('not found')) {
+      return new ResearchError(ResearchErrorCode.API_UNAVAILABLE, error.message, error);
+    }
+
+    // Generic error
+    return new ResearchError(defaultCode, error.message, error);
+  }
+
+  // Unknown error type
+  return new ResearchError(
+    defaultCode,
+    typeof error === 'string' ? error : 'Unknown error',
+    error,
+  );
+}
+
+/**
+ * Check if an error is transient (can be retried)
+ *
+ * @param error - The error to check
+ * @returns True if the error is transient
+ */
+export function isTransientError(error: ResearchError): boolean {
+  const transientCodes = [
+    ResearchErrorCode.NETWORK_ERROR,
+    ResearchErrorCode.API_RATE_LIMITED,
+    ResearchErrorCode.API_TIMEOUT,
+    ResearchErrorCode.API_UNAVAILABLE,
+    ResearchErrorCode.SEARXNG_START_FAILED,
+  ];
+
+  return transientCodes.includes(error.code);
+}
+
+/**
+ * Check if an error is fatal (cannot be retried)
+ *
+ * @param error - The error to check
+ * @returns True if the error is fatal
+ */
+export function isFatalError(error: ResearchError): boolean {
+  return !isTransientError(error);
+}

package/src/utils/research-export.ts

@@ -0,0 +1,199 @@
+/**
+ * Research Export Utility
+ *
+ * Resolves a smart output directory for research reports:
+ *
+ *   1. cwd is the user's home directory or a system directory → os.tmpdir()
+ *   2. cwd has a recognised first-level subdirectory            → that subdir
+ *      (research, docs, doc, ref, references, notes)
+ *   3. Otherwise                                               → cwd
+ *
+ * Cross-platform: works on Linux, macOS, and Windows.
+ * Subdir detection uses case-insensitive readdir matching so it works correctly
+ * on case-insensitive filesystems (macOS APFS, Windows NTFS).
+ */
+
+import { promises as fs } from 'node:fs';
+import { homedir, tmpdir, platform } from 'node:os';
+import { join, resolve, normalize, sep } from 'node:path';
+import { logger } from '../logger.ts';
+import { MAX_QUERY_LENGTH, MAX_EXPORT_RETRIES } from '../constants.ts';
+
+const LETTERS = 'abcdefghijklmnopqrstuvwxyz';
+const DIGITS = '0123456789';
+
+// Subdirectory names to probe, in priority order. Matched case-insensitively.
+const PREFERRED_SUBDIRS = [
+  'research',
+  'docs',
+  'doc',
+  'ref',
+  'references',
+  'notes',
+];
+
+// Unix/macOS paths that are never appropriate output destinations.
+const UNIX_SYSTEM_PREFIXES = [
+  '/',
+  '/bin', '/sbin', '/usr', '/lib', '/lib32', '/lib64',
+  '/etc', '/var', '/opt', '/root', '/proc', '/sys',
+  '/dev', '/run', '/boot', '/srv',
+  '/Applications', '/Library', '/System', // macOS
+];
+
+// Windows paths (lowercased for comparison) that are never appropriate.
+const WIN_SYSTEM_PREFIXES_LC = [
+  'c:\\windows',
+  'c:\\program files',
+  'c:\\program files (x86)',
+  'c:\\programdata',
+  'c:\\recovery',
+];
+
+/**
+ * Returns true when `dir` is the user's home directory or a system directory
+ * where writing research files would be unexpected or inappropriate.
+ */
+function isSafeToWriteDirectly(dir: string): boolean {
+  const normalized = normalize(resolve(dir));
+
+  // Reject the home directory itself
+  const home = normalize(resolve(homedir()));
+  if (normalized === home) return false;
+
+  if (platform() === 'win32') {
+    // Reject bare drive roots (e.g. C:\) and known system paths
+    if (/^[a-zA-Z]:\\?$/.test(normalized)) return false;
+    const lc = normalized.toLowerCase();
+    for (const prefix of WIN_SYSTEM_PREFIXES_LC) {
+      if (lc === prefix || lc.startsWith(prefix + sep) || lc.startsWith(prefix + '/')) {
+        return false;
+      }
+    }
+  } else {
+    // Unix / macOS
+    for (const prefix of UNIX_SYSTEM_PREFIXES) {
+      // Exact match or prefix + separator
+      if (normalized === prefix || normalized.startsWith(prefix + sep)) {
+        return false;
+      }
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Probe `cwd` for a recognised research-output subdirectory.
+ * Uses readdir + case-insensitive comparison so it works on any filesystem.
+ * Returns the first match in PREFERRED_SUBDIRS priority order, or null.
+ */
+async function findPreferredSubdir(cwd: string): Promise<string | null> {
+  let entries: string[];
+  try {
+    entries = await fs.readdir(cwd);
+  } catch {
+    return null;
+  }
+
+  for (const target of PREFERRED_SUBDIRS) {
+    const match = entries.find(e => e.toLowerCase() === target);
+    if (match === undefined) continue;
+    const candidate = join(cwd, match);
+    try {
+      const stat = await fs.stat(candidate);
+      if (stat.isDirectory()) return candidate;
+    } catch {
+      // Not a directory or not accessible — keep looking
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the directory where the report should be saved.
+ */
+async function resolveExportDir(cwd: string): Promise<string> {
+  if (!isSafeToWriteDirectly(cwd)) {
+    logger.log(`[export] cwd "${cwd}" is home/system — using tmpdir`);
+    return tmpdir();
+  }
+
+  const subdir = await findPreferredSubdir(cwd);
+  if (subdir !== null) {
+    logger.log(`[export] Using preferred subdir: ${subdir}`);
+    return subdir;
+  }
+
+  return cwd;
+}
+
+/**
+ * Sanitize query for use in a filename.
+ */
+function sanitizeQuery(query: string): string {
+  return query
+    .toLowerCase()
+    .trim()
+    .slice(0, MAX_QUERY_LENGTH)
+    .replace(/[^a-z0-9\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+/**
+ * Generate a random hash for collision avoidance.
+ * Format: letter + number (e.g., a3, b7, x9)
+ */
+function generateHash(): string {
+  const letter = LETTERS[Math.floor(Math.random() * LETTERS.length)]!;
+  const digit = DIGITS[Math.floor(Math.random() * DIGITS.length)]!;
+  return letter + digit;
+}
+
+/**
+ * Export a research report to the resolved output directory.
+ *
+ * @param query  - The research query (used to derive the filename)
+ * @param result - The report content
+ * @param _mode  - 'quick' | 'deep' (reserved for future use)
+ * @param cwd    - The working directory of the pi session
+ * @returns The saved file path, or null on failure
+ */
+export async function exportResearchReport(
+  query: string,
+  result: string,
+  _mode: 'quick' | 'deep',
+  cwd?: string,
+): Promise<string | null> {
+  const sanitizedQuery = sanitizeQuery(query);
+  const baseFilename = `pi-research-${sanitizedQuery}`;
+  const targetDir = await resolveExportDir(cwd ?? tmpdir());
+
+  for (let attempt = 0; attempt < MAX_EXPORT_RETRIES; attempt++) {
+    const hash = generateHash();
+    const filename = `${baseFilename}-${hash}.md`;
+    const filepath = join(targetDir, filename);
+
+    try {
+      await fs.writeFile(filepath, result, { flag: 'wx' });
+      logger.log(`[export] Research report saved to: ${filepath}`);
+      return filepath;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'EEXIST') continue;
+      logger.error(`[export] Failed to save research report:`, error);
+      return null;
+    }
+  }
+
+  logger.error(`[export] Failed to save research report after ${MAX_EXPORT_RETRIES} attempts (hash collision)`);
+  return null;
+}
+
+/**
+ * Append the saved-path footer to a research result string.
+ */
+export function appendExportMessage(result: string, filepath: string): string {
+  return result + `\n\n---\n\nResearch report saved to: ${filepath}`;
+}

package/src/utils/searxng-config.ts

@@ -0,0 +1,94 @@
+/**
+ * SearXNG Configuration Loader
+ *
+ * Reads the SearXNG config YAML and extracts active search engines.
+ * Ensures healthcheck and config stay synchronized.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { load } from 'js-yaml';
+import { logger } from '../logger.ts';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function parseYamlEngines(content: string): Array<{ name: string; disabled?: boolean }> {
+  const parsed = load(content) as { engines?: Array<{ name?: string; disabled?: boolean }> } | undefined;
+  const engines = parsed?.engines;
+
+  if (!Array.isArray(engines)) {
+    logger.warn('[searxng-config] No engines section found in config');
+    return [];
+  }
+
+  return engines
+    .filter((engine): engine is { name: string; disabled?: boolean } => typeof engine?.name === 'string')
+    .map((engine) => ({ name: engine.name.trim(), disabled: engine.disabled === true }));
+}
+
+/**
+ * Load SearXNG configuration and extract active general search engines
+ * Filters out:
+ * - Disabled engines
+ * - Category-specific engines (images, news, videos)
+ * - Category-restricted engines (stackoverflow, arxiv, semantic scholar, etc.)
+ * - Encyclopedic engines (wikipedia)
+ */
+export function getActiveSearxngEngines(): string[] {
+  try {
+    const configPath = join(__dirname, '../../config/searxng/default-settings.yml');
+    const content = readFileSync(configPath, 'utf-8');
+    const allEngines = parseYamlEngines(content);
+
+    // List of general purpose search engines (whitelist approach is safer)
+    const knownGeneralEngines = ['google', 'bing', 'brave', 'duckduckgo', 'startpage', 'mojeek', 'qwant'];
+
+    // Filter for general search engines only
+    const activeGeneralEngines = allEngines
+      .filter(
+        e =>
+          !e.disabled && // Not disabled
+          knownGeneralEngines.includes(e.name.toLowerCase()) // Only known general engines
+      )
+      .map(e => e.name.toLowerCase());
+
+    if (activeGeneralEngines.length === 0) {
+      logger.warn('[searxng-config] No active general search engines found in config');
+    }
+
+    logger.log(`[searxng-config] Active general search engines: [${activeGeneralEngines.join(', ')}]`);
+    return activeGeneralEngines;
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    logger.error('[searxng-config] Failed to load config:', msg);
+    // Fallback to known good defaults if config can't be loaded
+    return ['google', 'bing', 'brave'];
+  }
+}
+
+/**
+ * Validate that healthcheck engine list matches config
+ * Used in tests to catch drift
+ */
+export function validateEngineListConsistency(expectedEngines: string[]): {
+  isValid: boolean;
+  missing: string[];
+  extra: string[];
+} {
+  const actualEngines = getActiveSearxngEngines();
+  const actualSet = new Set(actualEngines);
+  const expectedSet = new Set(expectedEngines);
+
+  const missing = actualEngines.filter(e => !expectedSet.has(e));
+  const extra = expectedEngines.filter(e => !actualSet.has(e));
+
+  const isValid = missing.length === 0 && extra.length === 0;
+
+  return {
+    isValid,
+    missing,
+    extra,
+  };
+}