@nahisaho/shikigami-mcp-server 1.7.0 → 1.10.0

package/src/tools/visit/recovery/index.ts

@@ -0,0 +1,312 @@
+/**
+ * VisitRecoveryManager - ページ訪問リカバリーマネージャー
+ *
+ * TSK-1-004: VisitRecoveryManager実装
+ * REQ-SRCH-004-01: visit失敗時フォールバック
+ * REQ-SRCH-004-02: 自動リトライ
+ * REQ-SRCH-004-03: 結果マージ
+ * DES-SRCH-004: VisitRecoveryManager設計
+ */
+
+import { WaybackClient, type WaybackSnapshot, type WaybackClientConfig } from './wayback.js';
+import { RecoveryLogger, type RecoveryLoggerConfig, type ExtendedLogEntry } from '../../search/recovery/logger.js';
+
+/**
+ * ページ取得関数の型
+ */
+export type FetchFunction = (url: string) => Promise<PageFetchResult>;
+
+/**
+ * ページ取得結果
+ */
+export interface PageFetchResult {
+  /** 取得に成功したかどうか */
+  success: boolean;
+  /** コンテンツ（成功時） */
+  content?: string;
+  /** タイトル（成功時） */
+  title?: string;
+  /** エラーメッセージ（失敗時） */
+  error?: string;
+  /** HTTPステータスコード */
+  statusCode?: number;
+}
+
+/**
+ * リカバリー結果
+ */
+export interface VisitRecoveryResult {
+  /** 最終的に成功したかどうか */
+  success: boolean;
+  /** 元のURL */
+  originalUrl: string;
+  /** 実際に取得したURL（Wayback URLの可能性あり） */
+  usedUrl: string;
+  /** コンテンツ（成功時） */
+  content?: string;
+  /** タイトル（成功時） */
+  title?: string;
+  /** エラーメッセージ（失敗時） */
+  error?: string;
+  /** Wayback Machineを使用したかどうか */
+  usedWayback: boolean;
+  /** Waybackスナップショット情報 */
+  waybackSnapshot?: WaybackSnapshot;
+  /** 試行回数 */
+  attempts: number;
+  /** 処理時間（ms） */
+  durationMs: number;
+}
+
+/**
+ * VisitRecoveryManager 設定
+ */
+export interface VisitRecoveryConfig {
+  /** 最大リトライ回数（デフォルト: 2） */
+  maxRetries?: number;
+  /** リトライ間隔（ms、デフォルト: 1000） */
+  retryDelayMs?: number;
+  /** タイムアウト（ms、デフォルト: 30000） */
+  timeoutMs?: number;
+  /** Wayback Machineを使用するかどうか（デフォルト: true） */
+  enableWayback?: boolean;
+  /** WaybackClient設定 */
+  waybackConfig?: Partial<WaybackClientConfig>;
+  /** RecoveryLogger設定 */
+  loggerConfig?: Partial<RecoveryLoggerConfig>;
+  /** RecoveryLoggerインスタンス（省略時は新規作成） */
+  logger?: RecoveryLogger;
+}
+
+/**
+ * デフォルト設定
+ */
+export const DEFAULT_VISIT_RECOVERY_CONFIG: Required<Omit<VisitRecoveryConfig, 'waybackConfig' | 'loggerConfig' | 'logger'>> = {
+  maxRetries: 2,
+  retryDelayMs: 1000,
+  timeoutMs: 30000,
+  enableWayback: true,
+};
+
+/**
+ * VisitRecoveryManager - ページ訪問失敗時の自動リカバリー
+ */
+export class VisitRecoveryManager {
+  private readonly config: Required<Omit<VisitRecoveryConfig, 'waybackConfig' | 'loggerConfig' | 'logger'>>;
+  private readonly waybackClient: WaybackClient | null;
+  private readonly logger: RecoveryLogger;
+
+  constructor(config?: VisitRecoveryConfig) {
+    const { waybackConfig, loggerConfig, logger, ...restConfig } = config ?? {};
+    this.config = { ...DEFAULT_VISIT_RECOVERY_CONFIG, ...restConfig };
+    this.waybackClient = this.config.enableWayback ? new WaybackClient(waybackConfig) : null;
+    this.logger = logger ?? new RecoveryLogger(loggerConfig);
+  }
+
+  /**
+   * リカバリー付きページ取得を実行
+   * @param url 取得対象のURL
+   * @param fetchFn ページ取得関数
+   */
+  async recover(url: string, fetchFn: FetchFunction): Promise<VisitRecoveryResult> {
+    const startTime = Date.now();
+    let attempts = 0;
+    let lastError: string | undefined;
+
+    // 1. 元のURLでリトライ
+    for (let i = 0; i <= this.config.maxRetries; i++) {
+      attempts++;
+      const attemptStart = Date.now();
+
+      try {
+        const result = await this.fetchWithTimeout(fetchFn, url);
+        const durationMs = Date.now() - attemptStart;
+
+        if (result.success) {
+          this.logAttempt(url, url, 'direct', true, durationMs);
+
+          return {
+            success: true,
+            originalUrl: url,
+            usedUrl: url,
+            content: result.content,
+            title: result.title,
+            usedWayback: false,
+            attempts,
+            durationMs: Date.now() - startTime,
+          };
+        }
+
+        lastError = result.error ?? 'Unknown error';
+        this.logAttempt(url, url, 'direct', false, durationMs, lastError);
+      } catch (error) {
+        const durationMs = Date.now() - attemptStart;
+        lastError = error instanceof Error ? error.message : String(error);
+        this.logAttempt(url, url, 'direct', false, durationMs, lastError);
+      }
+
+      // リトライ前に待機
+      if (i < this.config.maxRetries) {
+        await this.delay(this.config.retryDelayMs);
+      }
+    }
+
+    // 2. Wayback Machineを使用してリカバリー
+    if (this.waybackClient) {
+      const waybackResult = await this.tryWayback(url, fetchFn, startTime, attempts);
+      if (waybackResult) {
+        return waybackResult;
+      }
+    }
+
+    // 3. すべての試行が失敗
+    return {
+      success: false,
+      originalUrl: url,
+      usedUrl: url,
+      error: lastError ?? 'All recovery attempts failed',
+      usedWayback: false,
+      attempts,
+      durationMs: Date.now() - startTime,
+    };
+  }
+
+  /**
+   * Wayback Machineを使用してリカバリーを試行
+   */
+  private async tryWayback(
+    originalUrl: string,
+    fetchFn: FetchFunction,
+    startTime: number,
+    currentAttempts: number
+  ): Promise<VisitRecoveryResult | null> {
+    if (!this.waybackClient) {
+      return null;
+    }
+
+    const waybackAttemptStart = Date.now();
+    const snapshot = await this.waybackClient.getSnapshot(originalUrl);
+
+    if (!snapshot?.available) {
+      this.logAttempt(originalUrl, originalUrl, 'wayback-check', false, Date.now() - waybackAttemptStart, 'No archive available');
+      return null;
+    }
+
+    const attemptStart = Date.now();
+    try {
+      const result = await this.fetchWithTimeout(fetchFn, snapshot.url);
+      const durationMs = Date.now() - attemptStart;
+
+      if (result.success) {
+        this.logAttempt(originalUrl, snapshot.url, 'wayback', true, durationMs);
+
+        return {
+          success: true,
+          originalUrl,
+          usedUrl: snapshot.url,
+          content: result.content,
+          title: result.title,
+          usedWayback: true,
+          waybackSnapshot: snapshot,
+          attempts: currentAttempts + 1,
+          durationMs: Date.now() - startTime,
+        };
+      }
+
+      this.logAttempt(originalUrl, snapshot.url, 'wayback', false, durationMs, result.error);
+    } catch (error) {
+      const durationMs = Date.now() - attemptStart;
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      this.logAttempt(originalUrl, snapshot.url, 'wayback', false, durationMs, errorMsg);
+    }
+
+    return null;
+  }
+
+  /**
+   * タイムアウト付きでページ取得を実行
+   */
+  private async fetchWithTimeout(fetchFn: FetchFunction, url: string): Promise<PageFetchResult> {
+    return new Promise<PageFetchResult>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error(`Request timed out after ${this.config.timeoutMs}ms`));
+      }, this.config.timeoutMs);
+
+      fetchFn(url)
+        .then((result) => {
+          clearTimeout(timer);
+          resolve(result);
+        })
+        .catch((error) => {
+          clearTimeout(timer);
+          reject(error);
+        });
+    });
+  }
+
+  /**
+   * リカバリー試行をログに記録
+   */
+  private logAttempt(
+    originalUrl: string,
+    usedUrl: string,
+    strategy: 'direct' | 'wayback' | 'wayback-check',
+    success: boolean,
+    durationMs: number,
+    error?: string
+  ): void {
+    const entry: Omit<ExtendedLogEntry, 'id'> = {
+      originalQuery: originalUrl,
+      alternativeQuery: usedUrl,
+      strategy,
+      resultCount: success ? 1 : 0,
+      success,
+      timestamp: new Date(),
+      durationMs,
+      type: 'visit',
+      error,
+    };
+
+    this.logger.log(entry);
+
+    // stderr にログ出力
+    console.error(
+      `[VisitRecovery] ${success ? '✓' : '✗'} "${originalUrl}" ${usedUrl !== originalUrl ? `→ "${usedUrl}"` : ''} (${strategy}) ${durationMs}ms`
+    );
+  }
+
+  /**
+   * 指定時間待機
+   */
+  private delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  /**
+   * RecoveryLoggerインスタンスを取得
+   */
+  getLogger(): RecoveryLogger {
+    return this.logger;
+  }
+
+  /**
+   * 統計情報を取得
+   */
+  getStats(): ReturnType<RecoveryLogger['getStats']> {
+    return this.logger.getStats();
+  }
+
+  /**
+   * WaybackClientインスタンスを取得
+   */
+  getWaybackClient(): WaybackClient | null {
+    return this.waybackClient;
+  }
+}
+
+/**
+ * VisitRecoveryManagerのファクトリ関数
+ */
+export function createVisitRecoveryManager(config?: VisitRecoveryConfig): VisitRecoveryManager {
+  return new VisitRecoveryManager(config);
+}

package/src/tools/visit/recovery/wayback.ts

@@ -0,0 +1,210 @@
+/**
+ * WaybackClient - Wayback Machine API クライアント
+ *
+ * TSK-1-003: WaybackClient実装
+ * REQ-SRCH-004-01: visit失敗時フォールバック
+ * DES-SRCH-004: VisitRecoveryManager設計
+ */
+
+/**
+ * Wayback Machine スナップショット情報
+ */
+export interface WaybackSnapshot {
+  /** スナップショットURL */
+  url: string;
+  /** 元のURL */
+  originalUrl: string;
+  /** アーカイブ日時（ISO 8601形式） */
+  timestamp: string;
+  /** 利用可能かどうか */
+  available: boolean;
+  /** HTTPステータスコード */
+  status?: number;
+}
+
+/**
+ * Wayback Machine API レスポンス
+ */
+export interface WaybackApiResponse {
+  archived_snapshots: {
+    closest?: {
+      url: string;
+      timestamp: string;
+      available: boolean;
+      status?: string;
+    };
+  };
+  url: string;
+}
+
+/**
+ * WaybackClient 設定
+ */
+export interface WaybackClientConfig {
+  /** APIベースURL（デフォルト: https://archive.org/wayback/available） */
+  apiBaseUrl?: string;
+  /** タイムアウト（ms、デフォルト: 10000） */
+  timeoutMs?: number;
+  /** 最大リトライ回数（デフォルト: 2） */
+  maxRetries?: number;
+  /** リトライ間隔（ms、デフォルト: 1000） */
+  retryDelayMs?: number;
+  /** User-Agent（デフォルト: SHIKIGAMI/1.10.0） */
+  userAgent?: string;
+}
+
+/**
+ * デフォルト設定
+ */
+export const DEFAULT_WAYBACK_CONFIG: Required<WaybackClientConfig> = {
+  apiBaseUrl: 'https://archive.org/wayback/available',
+  timeoutMs: 10000,
+  maxRetries: 2,
+  retryDelayMs: 1000,
+  userAgent: 'SHIKIGAMI/1.10.0',
+};
+
+/**
+ * WaybackClient - Wayback Machine APIを使ったページアーカイブ取得
+ */
+export class WaybackClient {
+  private readonly config: Required<WaybackClientConfig>;
+
+  constructor(config?: Partial<WaybackClientConfig>) {
+    this.config = { ...DEFAULT_WAYBACK_CONFIG, ...config };
+  }
+
+  /**
+   * 指定URLの最新アーカイブスナップショットを取得
+   * @param url 検索対象のURL
+   * @returns スナップショット情報（見つからない場合はnull）
+   */
+  async getSnapshot(url: string): Promise<WaybackSnapshot | null> {
+    let lastError: Error | null = null;
+
+    for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+      try {
+        return await this.fetchSnapshot(url);
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        if (attempt < this.config.maxRetries) {
+          await this.delay(this.config.retryDelayMs);
+        }
+      }
+    }
+
+    console.error(
+      `[WaybackClient] Failed to get snapshot for "${url}" after ${this.config.maxRetries + 1} attempts: ${lastError?.message}`
+    );
+    return null;
+  }
+
+  /**
+   * 指定URLの利用可能なアーカイブがあるかチェック
+   * @param url チェック対象のURL
+   * @returns 利用可能な場合true
+   */
+  async isArchived(url: string): Promise<boolean> {
+    const snapshot = await this.getSnapshot(url);
+    return snapshot?.available ?? false;
+  }
+
+  /**
+   * アーカイブされたコンテンツのURLを取得（リダイレクト用）
+   * @param url 元のURL
+   * @returns アーカイブURL（見つからない場合はnull）
+   */
+  async getArchiveUrl(url: string): Promise<string | null> {
+    const snapshot = await this.getSnapshot(url);
+    return snapshot?.available ? snapshot.url : null;
+  }
+
+  /**
+   * Wayback Machine APIを呼び出してスナップショットを取得
+   */
+  private async fetchSnapshot(url: string): Promise<WaybackSnapshot | null> {
+    const apiUrl = `${this.config.apiBaseUrl}?url=${encodeURIComponent(url)}`;
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs);
+
+    try {
+      const response = await fetch(apiUrl, {
+        method: 'GET',
+        headers: {
+          'User-Agent': this.config.userAgent,
+          Accept: 'application/json',
+        },
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+
+      const data = (await response.json()) as WaybackApiResponse;
+      return this.parseApiResponse(data, url);
+    } catch (error) {
+      clearTimeout(timeoutId);
+
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw new Error(`Request timed out after ${this.config.timeoutMs}ms`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * APIレスポンスをパース
+   */
+  private parseApiResponse(data: WaybackApiResponse, originalUrl: string): WaybackSnapshot | null {
+    const closest = data.archived_snapshots?.closest;
+
+    if (!closest) {
+      return null;
+    }
+
+    return {
+      url: closest.url,
+      originalUrl,
+      timestamp: this.formatTimestamp(closest.timestamp),
+      available: closest.available,
+      status: closest.status ? parseInt(closest.status, 10) : undefined,
+    };
+  }
+
+  /**
+   * Wayback Machine のタイムスタンプ（YYYYMMDDHHmmss）をISO 8601形式に変換
+   */
+  private formatTimestamp(timestamp: string): string {
+    if (timestamp.length !== 14) {
+      return timestamp;
+    }
+
+    const year = timestamp.substring(0, 4);
+    const month = timestamp.substring(4, 6);
+    const day = timestamp.substring(6, 8);
+    const hour = timestamp.substring(8, 10);
+    const minute = timestamp.substring(10, 12);
+    const second = timestamp.substring(12, 14);
+
+    return `${year}-${month}-${day}T${hour}:${minute}:${second}Z`;
+  }
+
+  /**
+   * 指定時間待機
+   */
+  private delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+/**
+ * WaybackClientのシングルトンインスタンスを作成
+ */
+export function createWaybackClient(config?: Partial<WaybackClientConfig>): WaybackClient {
+  return new WaybackClient(config);
+}

package/src/tools/visit.ts

@@ -4,13 +4,19 @@
  * Implements REQ-DR-002: Web検索 (page fetching)
  * Implements REQ-NF-007: プロバイダー設定ファイル対応
  * Implements REQ-PARSE-001: PDFコンテンツ抽出 (v1.7.0)
+ * Implements REQ-SRCH-004: ページ訪問リカバリー (v1.10.0)
  * Uses Jina AI Reader for LLM-optimized text extraction
  */
 
 import { getConfig } from '../config/loader.js';
 import { PdfParser } from './pdf-parser/index.js';
-import type { PdfParsingConfig } from '../config/types.js';
-import { DEFAULT_PDF_PARSING_CONFIG } from '../config/types.js';
+import type { PdfParsingConfig, VisitRecoveryConfig } from '../config/types.js';
+import { DEFAULT_PDF_PARSING_CONFIG, DEFAULT_VISIT_RECOVERY_CONFIG } from '../config/types.js';
+import {
+  VisitRecoveryManager,
+  type PageFetchResult,
+  type VisitRecoveryResult,
+} from './visit/recovery/index.js';
 
 export interface PageContent {
   url: string;
@@ -26,6 +32,17 @@ export interface PageContent {
     author?: string;
     creationDate?: string;
   };
+  /** v1.10.0: リカバリー情報 */
+  recovery?: {
+    /** Wayback Machine を使用したかどうか */
+    usedWayback: boolean;
+    /** 実際に取得したURL */
+    usedUrl: string;
+    /** 試行回数 */
+    attempts: number;
+    /** Waybackスナップショット日時（使用時） */
+    waybackTimestamp?: string;
+  };
 }
 
 const USER_AGENT =
@@ -58,6 +75,14 @@ function getPdfConfig(): PdfParsingConfig {
   return config.pdfParsing ?? DEFAULT_PDF_PARSING_CONFIG;
 }
 
+/**
+ * v1.10.0: Get visit recovery config
+ */
+function getVisitRecoveryConfig(): VisitRecoveryConfig {
+  const config = getConfig();
+  return config.visitRecovery ?? DEFAULT_VISIT_RECOVERY_CONFIG;
+}
+
 // v1.7.0: PDF parser instance (lazy initialized)
 let pdfParser: PdfParser | null = null;
 
@@ -68,6 +93,22 @@ function getPdfParser(): PdfParser {
   return pdfParser;
 }
 
+// v1.10.0: Visit recovery manager instance (lazy initialized)
+let visitRecoveryManager: VisitRecoveryManager | null = null;
+
+function getVisitRecoveryManager(): VisitRecoveryManager {
+  if (!visitRecoveryManager) {
+    const config = getVisitRecoveryConfig();
+    visitRecoveryManager = new VisitRecoveryManager({
+      maxRetries: config.maxRetries,
+      retryDelayMs: config.retryDelayMs,
+      timeoutMs: config.timeoutMs,
+      enableWayback: config.enableWayback,
+    });
+  }
+  return visitRecoveryManager;
+}
+
 async function rateLimit(): Promise<void> {
   const now = Date.now();
   const minInterval = getMinRequestInterval();
@@ -331,3 +372,119 @@ function extractTitleFromUrl(url: string): string {
     return 'PDF Document';
   }
 }
+
+// ============================================================
+// v1.10.0: リカバリー付きページ訪問 (REQ-SRCH-004)
+// ============================================================
+
+/**
+ * v1.10.0: ページ取得関数をPageFetchResult形式にラップ
+ */
+async function fetchPageAsResult(url: string): Promise<PageFetchResult> {
+  try {
+    const result = await visitPage(url);
+    
+    if (result.error) {
+      return {
+        success: false,
+        error: result.error,
+      };
+    }
+    
+    return {
+      success: true,
+      content: result.content,
+      title: result.title,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * v1.10.0: リカバリー付きページ訪問
+ * 
+ * REQ-SRCH-004-01: visit失敗時フォールバック（Wayback Machine）
+ * REQ-SRCH-004-02: 自動リトライ
+ * REQ-SRCH-004-03: 結果マージ
+ * 
+ * @param url 訪問対象のURL
+ * @param goal 訪問の目的（オプション）
+ * @returns ページコンテンツ
+ */
+export async function visitPageWithRecovery(url: string, goal?: string): Promise<PageContent> {
+  const fetchedAt = new Date().toISOString();
+  const config = getVisitRecoveryConfig();
+  
+  // リカバリーが無効な場合は従来の処理
+  if (!config.enabled) {
+    return await visitPage(url, goal);
+  }
+  
+  const manager = getVisitRecoveryManager();
+  
+  // v1.7.0: PDF検出は先に行う（リカバリー前）
+  const pdfConfig = getPdfConfig();
+  if (pdfConfig.enabled) {
+    const parser = getPdfParser();
+    const detection = parser.isPdfUrl(url);
+    
+    if (detection.isPdf) {
+      console.error(`[SHIKIGAMI] PDF detected (before recovery): ${url}`);
+      // PDFはそのまま従来処理（リカバリー対象外）
+      return await visitPage(url, goal);
+    }
+  }
+  
+  // リカバリー付き取得を実行
+  const result = await manager.recover(url, fetchPageAsResult);
+  
+  if (result.success) {
+    return {
+      url: result.originalUrl,
+      title: result.title ?? '',
+      content: result.content ?? '',
+      fetchedAt,
+      recovery: {
+        usedWayback: result.usedWayback,
+        usedUrl: result.usedUrl,
+        attempts: result.attempts,
+        waybackTimestamp: result.waybackSnapshot?.timestamp,
+      },
+    };
+  }
+  
+  // 全リカバリー失敗
+  return {
+    url,
+    title: '',
+    content: '',
+    fetchedAt,
+    error: result.error ?? 'Page fetch failed after all recovery attempts',
+    recovery: {
+      usedWayback: result.usedWayback,
+      usedUrl: result.usedUrl,
+      attempts: result.attempts,
+    },
+  };
+}
+
+/**
+ * v1.10.0: リカバリー統計を取得
+ */
+export function getVisitRecoveryStats(): ReturnType<VisitRecoveryManager['getStats']> | null {
+  if (!visitRecoveryManager) {
+    return null;
+  }
+  return visitRecoveryManager.getStats();
+}
+
+/**
+ * v1.10.0: リカバリーマネージャーをリセット（テスト用）
+ */
+export function resetVisitRecoveryManager(): void {
+  visitRecoveryManager = null;
+}