@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/research/cache/manager.js

@@ -0,0 +1,227 @@
+/**
+ * Cache manager for research API responses
+ *
+ * @module research/cache/manager
+ */
+import { promises as fs } from 'fs';
+import { join, dirname } from 'path';
+import { createHash } from 'crypto';
+import { ResearchError, ResearchErrorCode, } from '../types.js';
+/**
+ * Cache manager for file-based caching
+ */
+export class CacheManager {
+    config;
+    constructor(config) {
+        this.config = {
+            cacheDir: '.aiwg/research/cache',
+            defaultTtl: 86400, // 24 hours
+            ttlByEndpoint: {
+                'semantic-scholar': 604800, // 7 days
+                'crossref': 604800, // 7 days
+                'arxiv': 2592000, // 30 days (preprints don't change)
+                'unpaywall': 86400, // 24 hours
+            },
+            ...config,
+        };
+    }
+    /**
+     * Get cached data
+     */
+    async get(key) {
+        try {
+            const filePath = this.getFilePath(key);
+            const data = await fs.readFile(filePath, 'utf-8');
+            const entry = JSON.parse(data);
+            // Check if expired
+            if (this.isExpired(entry)) {
+                await this.delete(key);
+                return null;
+            }
+            return entry.data;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return null; // Cache miss
+            }
+            throw new ResearchError(ResearchErrorCode.RF_400, 'Cache read error', error);
+        }
+    }
+    /**
+     * Set cached data
+     */
+    async set(key, data, endpoint) {
+        try {
+            const ttl = endpoint
+                ? this.config.ttlByEndpoint?.[endpoint] || this.config.defaultTtl
+                : this.config.defaultTtl;
+            const entry = {
+                data,
+                cachedAt: new Date().toISOString(),
+                ttl,
+                key,
+            };
+            const filePath = this.getFilePath(key);
+            await this.ensureDir(dirname(filePath));
+            await fs.writeFile(filePath, JSON.stringify(entry, null, 2), 'utf-8');
+        }
+        catch (error) {
+            throw new ResearchError(ResearchErrorCode.RF_401, 'Cache write error', error);
+        }
+    }
+    /**
+     * Delete cached data
+     */
+    async delete(key) {
+        try {
+            const filePath = this.getFilePath(key);
+            await fs.unlink(filePath);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw new ResearchError(ResearchErrorCode.RF_402, 'Cache deletion error', error);
+            }
+        }
+    }
+    /**
+     * Clear all cache
+     */
+    async clear() {
+        try {
+            const files = await this.listCacheFiles();
+            await Promise.all(files.map((file) => fs.unlink(file)));
+        }
+        catch (error) {
+            throw new ResearchError(ResearchErrorCode.RF_402, 'Cache clear error', error);
+        }
+    }
+    /**
+     * Clear expired entries
+     */
+    async clearExpired() {
+        try {
+            const files = await this.listCacheFiles();
+            let cleared = 0;
+            for (const file of files) {
+                try {
+                    const data = await fs.readFile(file, 'utf-8');
+                    const entry = JSON.parse(data);
+                    if (this.isExpired(entry)) {
+                        await fs.unlink(file);
+                        cleared++;
+                    }
+                }
+                catch {
+                    // Skip invalid files
+                }
+            }
+            return cleared;
+        }
+        catch (error) {
+            throw new ResearchError(ResearchErrorCode.RF_402, 'Cache cleanup error', error);
+        }
+    }
+    /**
+     * Get cache statistics
+     */
+    async getStats() {
+        try {
+            const files = await this.listCacheFiles();
+            let expiredEntries = 0;
+            let sizeBytes = 0;
+            for (const file of files) {
+                try {
+                    const stats = await fs.stat(file);
+                    sizeBytes += stats.size;
+                    const data = await fs.readFile(file, 'utf-8');
+                    const entry = JSON.parse(data);
+                    if (this.isExpired(entry)) {
+                        expiredEntries++;
+                    }
+                }
+                catch {
+                    // Skip invalid files
+                }
+            }
+            return {
+                totalEntries: files.length,
+                expiredEntries,
+                sizeBytes,
+            };
+        }
+        catch (error) {
+            throw new ResearchError(ResearchErrorCode.RF_400, 'Cache stats error', error);
+        }
+    }
+    /**
+     * Generate cache key from input
+     */
+    generateKey(endpoint, params) {
+        // Sort keys to ensure consistent hashing
+        const sortedKeys = Object.keys(params).sort();
+        const sortedParams = {};
+        for (const key of sortedKeys) {
+            sortedParams[key] = params[key];
+        }
+        const normalized = JSON.stringify({ endpoint, params: sortedParams });
+        return createHash('sha256').update(normalized).digest('hex');
+    }
+    /**
+     * Check if cache entry is expired
+     */
+    isExpired(entry) {
+        const cachedTime = new Date(entry.cachedAt).getTime();
+        const expiryTime = cachedTime + entry.ttl * 1000;
+        return Date.now() > expiryTime;
+    }
+    /**
+     * Get file path for cache key
+     */
+    getFilePath(key) {
+        // Use first 2 chars for subdirectory to avoid too many files in one dir
+        const subdir = key.substring(0, 2);
+        return join(this.config.cacheDir, subdir, `${key}.json`);
+    }
+    /**
+     * Ensure directory exists
+     */
+    async ensureDir(dir) {
+        try {
+            await fs.mkdir(dir, { recursive: true });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST') {
+                throw error;
+            }
+        }
+    }
+    /**
+     * List all cache files
+     */
+    async listCacheFiles() {
+        const files = [];
+        try {
+            const entries = await fs.readdir(this.config.cacheDir, {
+                withFileTypes: true,
+            });
+            for (const entry of entries) {
+                const fullPath = join(this.config.cacheDir, entry.name);
+                if (entry.isDirectory()) {
+                    const subFiles = await fs.readdir(fullPath);
+                    for (const file of subFiles) {
+                        if (file.endsWith('.json')) {
+                            files.push(join(fullPath, file));
+                        }
+                    }
+                }
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+        return files;
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/src/research/clients/arxiv.js

@@ -0,0 +1,156 @@
+/**
+ * arXiv API client
+ *
+ * @module research/clients/arxiv
+ */
+import { BaseClient } from './base.js';
+import { ResearchError, ResearchErrorCode, } from '../types.js';
+/**
+ * arXiv API client
+ */
+export class ArxivClient extends BaseClient {
+    constructor(config) {
+        super({
+            baseUrl: 'http://export.arxiv.org/api',
+            timeout: 30000,
+            rateLimit: {
+                maxTokens: 3,
+                refillRate: 1 / 3, // 1 request per 3 seconds
+                currentTokens: 3,
+                lastRefill: Date.now(),
+            },
+            retry: {
+                maxRetries: 3,
+                initialDelay: 1000,
+                maxDelay: 10000,
+                backoffMultiplier: 2,
+            },
+            ...config,
+        });
+    }
+    /**
+     * Get paper by arXiv ID
+     */
+    async getPaperById(arxivId) {
+        // Normalize arXiv ID (remove version if present)
+        const normalizedId = arxivId.replace(/v\d+$/, '');
+        const url = this.buildUrl('/query', {
+            id_list: normalizedId,
+            max_results: 1,
+        });
+        const xmlText = await this.requestXml(url);
+        const papers = this.parseAtomFeed(xmlText);
+        if (papers.length === 0) {
+            throw new ResearchError(ResearchErrorCode.RF_300, `arXiv paper not found: ${arxivId}`);
+        }
+        return papers[0];
+    }
+    /**
+     * Search papers by query
+     */
+    async search(query, options = {}) {
+        const { limit = 10, offset = 0 } = options;
+        const url = this.buildUrl('/query', {
+            search_query: query,
+            start: offset,
+            max_results: limit,
+        });
+        const xmlText = await this.requestXml(url);
+        const papers = this.parseAtomFeed(xmlText);
+        // arXiv doesn't provide total count, so we estimate
+        const hasMore = papers.length === limit;
+        return {
+            total: hasMore ? offset + limit + 1 : offset + papers.length,
+            papers,
+            offset,
+            limit,
+            hasMore,
+        };
+    }
+    /**
+     * Request XML from arXiv API
+     */
+    async requestXml(url) {
+        await this.rateLimiter.acquire();
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+        try {
+            const response = await fetch(url, {
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new ResearchError(ResearchErrorCode.RF_200, `arXiv API error: ${response.status}`);
+            }
+            return await response.text();
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new ResearchError(ResearchErrorCode.RF_104, `Request timeout after ${this.config.timeout}ms`, error);
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Parse Atom XML feed from arXiv
+     */
+    parseAtomFeed(xmlText) {
+        // Simple XML parsing for arXiv Atom feed
+        const papers = [];
+        // Extract entries
+        const entryRegex = /<entry>([\s\S]*?)<\/entry>/g;
+        const entries = xmlText.match(entryRegex) || [];
+        for (const entry of entries) {
+            papers.push(this.parseEntry(entry));
+        }
+        return papers;
+    }
+    /**
+     * Parse a single entry from the feed
+     */
+    parseEntry(entry) {
+        const extractTag = (tag) => {
+            const regex = new RegExp(`<${tag}[^>]*>([\\s\\S]*?)</${tag}>`, 'i');
+            const match = entry.match(regex);
+            return match ? match[1].trim() : '';
+        };
+        const extractAllTags = (tag) => {
+            const regex = new RegExp(`<${tag}[^>]*>([\\s\\S]*?)</${tag}>`, 'gi');
+            const matches = entry.match(regex) || [];
+            return matches.map((m) => {
+                const contentMatch = m.match(new RegExp(`<${tag}[^>]*>([\\s\\S]*?)</${tag}>`, 'i'));
+                return contentMatch ? contentMatch[1].trim() : '';
+            });
+        };
+        const id = extractTag('id');
+        const arxivId = id.split('/').pop()?.replace(/v\d+$/, '') || '';
+        const title = extractTag('title').replace(/\s+/g, ' ');
+        const summary = extractTag('summary').replace(/\s+/g, ' ');
+        const published = extractTag('published');
+        const year = parseInt(published.substring(0, 4), 10) || 0;
+        const authorNames = extractAllTags('name');
+        const authors = authorNames.map((name) => ({ name }));
+        // Extract DOI if present
+        const doiMatch = entry.match(/doi:([^\s<]+)/i);
+        const doi = doiMatch ? doiMatch[1] : undefined;
+        // Extract PDF link
+        const pdfLinkMatch = entry.match(/<link[^>]*title="pdf"[^>]*href="([^"]+)"/i);
+        const pdfUrl = pdfLinkMatch ? pdfLinkMatch[1] : undefined;
+        return {
+            id: arxivId,
+            title,
+            authors,
+            year,
+            abstract: summary,
+            arxivId,
+            doi,
+            pdfUrl,
+            type: 'preprint',
+            source: 'arxiv',
+            retrievedAt: new Date().toISOString(),
+        };
+    }
+}
+//# sourceMappingURL=arxiv.js.map

package/dist/src/research/clients/base.js

@@ -0,0 +1,197 @@
+/**
+ * Base API client with rate limiting and retry logic
+ *
+ * @module research/clients/base
+ */
+import { ResearchError, ResearchErrorCode, } from '../types.js';
+/**
+ * Token bucket rate limiter
+ */
+export class RateLimiter {
+    config;
+    tokens;
+    lastRefill;
+    constructor(config) {
+        this.config = config;
+        this.tokens = config.currentTokens;
+        this.lastRefill = config.lastRefill; // Use config value, not Date.now()
+    }
+    /**
+     * Refill tokens based on elapsed time
+     */
+    refill() {
+        const now = Date.now();
+        const elapsed = (now - this.lastRefill) / 1000; // Convert to seconds
+        const tokensToAdd = elapsed * this.config.refillRate;
+        this.tokens = Math.min(this.config.maxTokens, this.tokens + tokensToAdd);
+        this.lastRefill = now;
+    }
+    /**
+     * Acquire a token, waiting if necessary
+     */
+    async acquire() {
+        this.refill();
+        if (this.tokens >= 1) {
+            this.tokens -= 1;
+            return;
+        }
+        // Calculate wait time
+        const deficit = 1 - this.tokens;
+        const waitMs = (deficit / this.config.refillRate) * 1000;
+        await this.sleep(waitMs);
+        // Refill again after waiting
+        this.refill();
+        this.tokens -= 1;
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Get current token count (for testing)
+     */
+    getCurrentTokens() {
+        this.refill();
+        return this.tokens;
+    }
+}
+/**
+ * Base API client with common functionality
+ */
+export class BaseClient {
+    config;
+    rateLimiter;
+    retryConfig;
+    constructor(config) {
+        this.config = config;
+        this.rateLimiter = new RateLimiter(config.rateLimit);
+        this.retryConfig = config.retry;
+    }
+    /**
+     * Execute an HTTP request with rate limiting and retry logic
+     */
+    async request(url, options = {}) {
+        // Apply rate limiting
+        await this.rateLimiter.acquire();
+        // Execute with retry
+        return this.executeWithRetry(url, options);
+    }
+    /**
+     * Execute request with exponential backoff retry
+     */
+    async executeWithRetry(url, options, attempt = 0, firstError) {
+        const controller = new AbortController();
+        let timeoutId;
+        try {
+            // Create timeout promise
+            const timeoutPromise = new Promise((_, reject) => {
+                timeoutId = setTimeout(() => {
+                    controller.abort();
+                    reject(new ResearchError(ResearchErrorCode.RF_104, `Request timeout after ${this.config.timeout}ms`));
+                }, this.config.timeout);
+            });
+            // Create fetch promise
+            const fetchPromise = fetch(url, {
+                ...options,
+                signal: controller.signal,
+            });
+            // Race between fetch and timeout
+            const response = await Promise.race([fetchPromise, timeoutPromise]);
+            // Clear timeout if fetch completed first
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+            if (!response.ok) {
+                const error = await this.handleHttpError(response);
+                throw error;
+            }
+            return (await response.json());
+        }
+        catch (error) {
+            // Clear timeout on error
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+            // Handle abort (timeout)
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new ResearchError(ResearchErrorCode.RF_104, `Request timeout after ${this.config.timeout}ms`, error);
+            }
+            // Track the first error for better error reporting
+            const currentFirstError = firstError || (error instanceof ResearchError ? error : undefined);
+            // Don't retry ResearchErrors (they're already handled)
+            if (error instanceof ResearchError) {
+                // Retry on transient errors
+                if (this.isRetriable(error) && attempt < this.retryConfig.maxRetries) {
+                    const delay = this.calculateBackoff(attempt);
+                    await this.sleep(delay);
+                    return this.executeWithRetry(url, options, attempt + 1, currentFirstError);
+                }
+                throw error;
+            }
+            // Retry on network errors
+            if (attempt < this.retryConfig.maxRetries) {
+                const delay = this.calculateBackoff(attempt);
+                await this.sleep(delay);
+                return this.executeWithRetry(url, options, attempt + 1, currentFirstError);
+            }
+            // If we have a first error from an HTTP response, throw that instead of generic network error
+            if (currentFirstError) {
+                throw currentFirstError;
+            }
+            throw new ResearchError(ResearchErrorCode.RF_500, 'Network error', error);
+        }
+    }
+    /**
+     * Handle HTTP error responses
+     */
+    async handleHttpError(response) {
+        const status = response.status;
+        if (status === 404) {
+            return new ResearchError(ResearchErrorCode.RF_300, 'Resource not found');
+        }
+        if (status === 429) {
+            return new ResearchError(ResearchErrorCode.RF_103, 'Rate limit exceeded');
+        }
+        if (status === 401 || status === 403) {
+            return new ResearchError(ResearchErrorCode.RF_102, 'Invalid API key or unauthorized');
+        }
+        if (status >= 500) {
+            return new ResearchError(ResearchErrorCode.RF_200, 'API server error');
+        }
+        return new ResearchError(ResearchErrorCode.RF_100, `HTTP error ${status}`);
+    }
+    /**
+     * Determine if an error is retriable
+     */
+    isRetriable(error) {
+        if (error instanceof ResearchError) {
+            // Only retry on server errors (not rate limits or client errors)
+            return error.code === ResearchErrorCode.RF_200;
+        }
+        // Retry on network errors
+        return true;
+    }
+    /**
+     * Calculate exponential backoff delay
+     */
+    calculateBackoff(attempt) {
+        const delay = this.retryConfig.initialDelay *
+            Math.pow(this.retryConfig.backoffMultiplier, attempt);
+        return Math.min(delay, this.retryConfig.maxDelay);
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Build URL with query parameters
+     */
+    buildUrl(path, params) {
+        const url = new URL(path, this.config.baseUrl);
+        Object.entries(params).forEach(([key, value]) => {
+            if (value !== undefined) {
+                url.searchParams.append(key, String(value));
+            }
+        });
+        return url.toString();
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/src/research/clients/crossref.js

@@ -0,0 +1,112 @@
+/**
+ * CrossRef API client
+ *
+ * @module research/clients/crossref
+ */
+import { BaseClient } from './base.js';
+/**
+ * CrossRef API client
+ */
+export class CrossRefClient extends BaseClient {
+    constructor(config) {
+        super({
+            baseUrl: 'https://api.crossref.org',
+            timeout: 30000,
+            rateLimit: {
+                maxTokens: 50,
+                refillRate: 1, // 1 request per second (polite pool)
+                currentTokens: 50,
+                lastRefill: Date.now(),
+            },
+            retry: {
+                maxRetries: 3,
+                initialDelay: 1000,
+                maxDelay: 10000,
+                backoffMultiplier: 2,
+            },
+            ...config,
+        });
+    }
+    /**
+     * Get paper by DOI
+     */
+    async getPaperByDoi(doi) {
+        const url = this.buildUrl(`/works/${encodeURIComponent(doi)}`, {});
+        const response = await this.request(url);
+        return this.transformResponse(response.message);
+    }
+    /**
+     * Search papers by query
+     */
+    async search(query, options = {}) {
+        const { limit = 10, offset = 0 } = options;
+        const url = this.buildUrl('/works', {
+            query,
+            rows: limit,
+            offset,
+        });
+        const response = await this.request(url);
+        return {
+            total: response.message['total-results'],
+            papers: response.message.items.map((paper) => this.transformResponse(paper)),
+            offset,
+            limit,
+            hasMore: offset + response.message.items.length < response.message['total-results'],
+        };
+    }
+    /**
+     * Transform CrossRef response to ResearchPaper
+     */
+    transformResponse(response) {
+        const authors = response.author?.map((author) => {
+            const name = [author.given, author.family]
+                .filter(Boolean)
+                .join(' ');
+            const affiliations = author.affiliation?.map((aff) => aff.name) || [];
+            return {
+                name,
+                affiliations,
+            };
+        }) || [];
+        const year = response.published?.['date-parts']?.[0]?.[0] || 0;
+        const title = Array.isArray(response.title)
+            ? response.title[0]
+            : response.title || '';
+        const venue = Array.isArray(response['container-title'])
+            ? response['container-title'][0]
+            : response['container-title'] || '';
+        return {
+            id: response.DOI,
+            title,
+            authors,
+            year,
+            abstract: response.abstract,
+            doi: response.DOI,
+            venue,
+            citationCount: response['is-referenced-by-count'],
+            type: this.mapType(response.type),
+            source: 'crossref',
+            retrievedAt: new Date().toISOString(),
+        };
+    }
+    /**
+     * Map CrossRef type to ResearchPaper type
+     */
+    mapType(crossrefType) {
+        if (!crossrefType)
+            return 'other';
+        const type = crossrefType.toLowerCase();
+        if (type.includes('journal'))
+            return 'journal';
+        if (type.includes('proceedings'))
+            return 'conference';
+        if (type.includes('posted-content'))
+            return 'preprint';
+        if (type.includes('book'))
+            return 'book';
+        if (type.includes('dissertation') || type.includes('thesis'))
+            return 'thesis';
+        return 'other';
+    }
+}
+//# sourceMappingURL=crossref.js.map