wtf-p 0.2.0 → 0.4.0

package/bin/lib/citation-ranker.js

@@ -0,0 +1,133 @@
+/**
+ * Citation Ranker
+ * 
+ * Ranks papers based on multidimensional impact score:
+ * - Citation Count (Log scaled)
+ * - Velocity (Citations per month)
+ * - Recency (Decay over time)
+ * - Venue (Tiered scoring)
+ */
+
+// Venue Tiers
+const VENUE_TIERS = {
+  TIER_1: [
+    // AI/ML
+    "neurips", "nips", "icml", "iclr", "cvpr", "iccv", "eccv", "acl", "emnlp", "naacl",
+    "aaai", "ijcai", "kdd", "www", "sigir", "chi",
+    // Systems
+    "osdi", "sosp", "nsdi", "eurosys", "atc", "fast", "sigcomm", "mobicom",
+    // Journals
+    "nature", "science", "pnas", "cell", "lancet", "nejm", "jama",
+    "ieee transactions", "acm computing surveys", "jmlr", "journal of machine learning research"
+  ],
+  TIER_2: [
+    "coling", "wsdm", "cikm", "pakdd", "ijcnn", "icra", "iros",
+    "middleware", "cloud", "sc", "hpdc", "cluster"
+  ],
+  PREPRINT: [
+    "arxiv", "biorxiv", "medrxiv", "ssrn", "workshop"
+  ]
+};
+
+/**
+ * Score a venue name
+ * @param {string} venue 
+ * @returns {number} 0.0 to 1.0
+ */
+function scoreVenue(venue) {
+  if (!venue) return 0.2;
+  const v = venue.toLowerCase();
+  
+  if (VENUE_TIERS.TIER_1.some(t => v.includes(t))) return 1.0;
+  if (VENUE_TIERS.TIER_2.some(t => v.includes(t))) return 0.7;
+  if (VENUE_TIERS.PREPRINT.some(t => v.includes(t))) return 0.3;
+  
+  return 0.5; // Unknown venue default
+}
+
+/**
+ * Calculate citation velocity
+ * @param {number} citations 
+ * @param {number} year 
+ * @returns {number} Citations per month
+ */
+function calculateVelocity(citations, year) {
+  if (!citations || !year) return 0;
+  const now = new Date();
+  const currentYear = now.getFullYear();
+  const currentMonth = now.getMonth(); // 0-11
+  
+  // Calculate months since publication (assuming Jan 1st of year)
+  // If current year, use months passed. If past year, (diff * 12) + currentMonth.
+  let monthsSince = (currentYear - year) * 12 + currentMonth;
+  
+  // Guard against divide by zero or negative (future dates)
+  monthsSince = Math.max(1, monthsSince);
+  
+  return citations / monthsSince;
+}
+
+/**
+ * Calculate impact score for a paper
+ * @param {Object} paper 
+ * @param {string} intent "seminal" | "recent" | "specific" | "balanced"
+ */
+function calculateScore(paper, intent = "balanced") {
+  const now = new Date().getFullYear();
+  const year = paper.year || now;
+  const age = Math.max(0, now - year);
+  const citations = paper.citationCount || 0;
+  const velocity = calculateVelocity(citations, year);
+  
+  // Normalize factors (approximate ranges)
+  // Citations: log10(100,000) = 5. So score is 0-1.
+  const citationScore = Math.min(1, Math.log10(citations + 1) / 5);
+  
+  // Velocity: 100 cites/month is huge. Normalize to 0-1.
+  const velocityScore = Math.min(1, velocity / 100);
+  
+  // Recency: Linear decay over 10 years. 0 if > 10 years old.
+  const recencyScore = Math.max(0, 1 - (age / 10));
+  
+  const venueScore = scoreVenue(paper.venue);
+  
+  // Weights based on intent
+  const weights = {
+    seminal:  { citation: 0.6, velocity: 0.2, recency: 0.1, venue: 0.1 },
+    recent:   { citation: 0.2, velocity: 0.3, recency: 0.4, venue: 0.1 },
+    specific: { citation: 0.1, velocity: 0.1, recency: 0.1, venue: 0.1 }, // Ranking less important for specific lookup
+    balanced: { citation: 0.4, velocity: 0.3, recency: 0.2, venue: 0.1 }
+  };
+  
+  const w = weights[intent] || weights.balanced;
+  
+  return (
+    citationScore * w.citation +
+    velocityScore * w.velocity +
+    recencyScore * w.recency +
+    venueScore * w.venue
+  );
+}
+
+/**
+ * Rank a list of papers
+ * @param {Array} papers 
+ * @param {string} intent 
+ * @returns {Array} Sorted papers with score attached
+ */
+function rank(papers, intent = "balanced") {
+  const scored = papers.map(p => ({
+    ...p,
+    wtfp_score: calculateScore(p, intent),
+    wtfp_velocity: calculateVelocity(p.citationCount, p.year)
+  }));
+  
+  return scored.sort((a, b) => b.wtfp_score - a.wtfp_score);
+}
+
+module.exports = {
+  rank,
+  calculateScore,
+  calculateVelocity,
+  scoreVenue
+};

package/bin/lib/manifest.js

@@ -0,0 +1,59 @@
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '../..');
+
+const MANIFEST = {
+  claude: {
+    name: 'Claude Code',
+    configDirEnv: 'CLAUDE_CONFIG_DIR',
+    defaultDir: '.claude',
+    components: [
+      {
+        id: 'workflows',
+        src: path.join(ROOT, 'core', 'write-the-f-paper'),
+        dest: 'write-the-f-paper',
+        type: 'dir'
+      },
+      {
+        id: 'commands',
+        src: path.join(ROOT, 'vendors', 'claude', 'commands', 'wtfp'),
+        dest: 'commands/wtfp',
+        type: 'dir'
+      },
+      {
+        id: 'skills',
+        src: path.join(ROOT, 'vendors', 'claude', 'skills', 'wtfp'),
+        dest: 'skills/wtfp',
+        type: 'dir'
+      },
+      {
+        id: 'agents',
+        src: path.join(ROOT, 'vendors', 'claude', 'agents', 'wtfp'),
+        dest: 'agents/wtfp',
+        type: 'dir'
+      },
+      {
+        id: 'mcp',
+        src: path.join(ROOT, 'vendors', 'claude', 'mcp'),
+        dest: 'mcp',
+        type: 'dir'
+      },
+      {
+        id: 'scripts',
+        src: path.join(ROOT, 'bin', 'lib'),
+        dest: 'bin',
+        type: 'dir'
+      },
+      {
+        id: 'plugin',
+        src: path.join(ROOT, 'vendors', 'claude', '.claude-plugin'),
+        dest: '.claude-plugin',
+        type: 'dir'
+      }
+    ]
+  },
+  // Future:
+  // gemini: { ... }
+};
+
+module.exports = MANIFEST;

package/bin/lib/scholar-lookup.js

@@ -0,0 +1,188 @@
+const https = require('https');
+const querystring = require('querystring');
+
+/**
+ * SerpAPI Google Scholar Wrapper
+ * 
+ * Provides access to Google Scholar data via SerpAPI.
+ * Used for high-value "seminal" queries to get citation velocity and cluster IDs.
+ * 
+ * Env:
+ *  - SERPAPI_KEY: Required for operation.
+ */
+
+const HOST = 'serpapi.com';
+const PATH = '/search';
+
+const usage = {
+  queries: 0,
+  // Default budget: 100 queries/month (~$5)
+  monthlyBudget: 100,
+  
+  canQuery() {
+    return this.queries < this.monthlyBudget;
+  },
+  
+  recordQuery() {
+    this.queries++;
+    if (this.queries % 10 === 0) {
+      // console.error(`[Scholar] API usage: ${this.queries}/${this.monthlyBudget}`);
+    }
+  }
+};
+
+function getApiKey() {
+  return process.env.SERPAPI_KEY;
+}
+
+function isAvailable() {
+  return !!getApiKey();
+}
+
+function request(params) {
+  return new Promise((resolve, reject) => {
+    const key = getApiKey();
+    if (!key) {
+      return reject(new Error('SERPAPI_KEY not set'));
+    }
+    if (!usage.canQuery()) {
+      return reject(new Error('Monthly budget exceeded'));
+    }
+
+    usage.recordQuery();
+
+    const q = querystring.stringify({
+      ...params,
+      api_key: key,
+      engine: 'google_scholar'
+    });
+
+    const options = {
+      hostname: HOST,
+      path: `${PATH}?${q}`,
+      method: 'GET'
+    };
+
+    const req = https.request(options, (res) => {
+      let data = '';
+      res.on('data', c => data += c);
+      res.on('end', () => {
+        if (res.statusCode !== 200) {
+          return reject(new Error(`SerpAPI Error: ${res.statusCode} ${data}`));
+        }
+        try {
+          resolve(JSON.parse(data));
+        } catch (e) {
+          reject(e);
+        }
+      });
+    });
+
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+/**
+ * Search Google Scholar
+ * @param {string} query 
+ * @param {Object} options { yearLow, yearHigh, limit }
+ */
+async function search(query, options = {}) {
+  const params = {
+    q: query,
+    num: options.limit || 10
+  };
+  
+  if (options.yearLow) params.as_ylo = options.yearLow;
+  if (options.yearHigh) params.as_yhi = options.yearHigh;
+
+  const data = await request(params);
+  return (data.organic_results || []).map(mapResult);
+}
+
+/**
+ * Get paper by Cluster ID
+ * @param {string} clusterId 
+ */
+async function getByClusterId(clusterId) {
+  const data = await request({ cluster: clusterId });
+  // When searching by cluster, it returns list of versions.
+  // We usually want the first one or metadata about the cluster.
+  // SerpAPI "cluster" usually returns "organic_results" which are the versions.
+  const results = data.organic_results || [];
+  if (results.length > 0) return mapResult(results[0]);
+  return null;
+}
+
+/**
+ * Get citing papers
+ * @param {string} clusterId 
+ * @param {number} limit 
+ */
+async function getCitingPapers(clusterId, limit = 10) {
+  const data = await request({ 
+    cites: clusterId,
+    num: limit 
+  });
+  return (data.organic_results || []).map(mapResult);
+}
+
+function mapResult(item) {
+  // Extract cluster ID
+  let clusterId = null;
+  // Try to find it in links or specific fields if SerpAPI provides it directly
+  // SerpAPI usually puts it in inline_links -> cited_by -> serpapi_link (cites=ID)
+  // or versions -> serpapi_link (cluster=ID)
+  
+  if (item.inline_links && item.inline_links.cited_by && item.inline_links.cited_by.serpapi_link) {
+    const match = item.inline_links.cited_by.serpapi_link.match(/cites=(\w+)/);
+    if (match) clusterId = match[1];
+  }
+  
+  return {
+    source: 'google_scholar',
+    title: item.title,
+    clusterId: clusterId || item.cluster_id, // Sometimes provided directly
+    link: item.link,
+    snippet: item.snippet,
+    publication_info: item.publication_info,
+    citationCount: item.inline_links && item.inline_links.cited_by ? item.inline_links.cited_by.total : 0,
+    year: extractYear(item.publication_info ? item.publication_info.summary : ''),
+    authors: extractAuthors(item.publication_info ? item.publication_info.summary : ''),
+    venue: extractVenue(item.publication_info ? item.publication_info.summary : '')
+  };
+}
+
+function extractYear(summary) {
+  const match = summary.match(/\b(19|20)\d{2}\b/);
+  return match ? parseInt(match[0]) : null;
+}
+
+function extractAuthors(summary) {
+  // "A Author, B Author - Venue, 2020 - publisher"
+  if (!summary) return [];
+  const parts = summary.split('-');
+  if (parts.length > 0) {
+    return parts[0].split(',').map(s => ({ name: s.trim() }));
+  }
+  return [];
+}
+
+function extractVenue(summary) {
+  if (!summary) return null;
+  const parts = summary.split('-');
+  if (parts.length > 1) {
+    // "Venue, Year" usually
+    return parts[1].split(',')[0].trim();
+  }
+  return null;
+}
+
+module.exports = {
+  isAvailable,
+  search,
+  getByClusterId,
+  getCitingPapers,
+  usage
+};

package/bin/lib/semantic-scholar.js

@@ -0,0 +1,184 @@
+const https = require('https');
+const querystring = require('querystring');
+
+/**
+ * Semantic Scholar API Wrapper
+ * 
+ * Provides search and lookup capabilities for Semantic Scholar Graph API v1.
+ * Handles rate limiting with exponential backoff.
+ * 
+ * Env:
+ *  - S2_API_KEY: Optional API key for higher rate limits.
+ */
+
+const API_KEY = process.env.S2_API_KEY;
+const BASE_HOST = 'api.semanticscholar.org';
+const BASE_PATH = '/graph/v1';
+
+const RETRY_CONFIG = {
+  maxRetries: 5,
+  baseDelay: 1000,
+  maxDelay: 16000
+};
+
+class SemanticScholarError extends Error {
+  constructor(message, statusCode, retryAfter) {
+    super(message);
+    this.name = 'SemanticScholarError';
+    this.statusCode = statusCode;
+    this.retryAfter = retryAfter;
+  }
+}
+
+/**
+ * Sleep helper
+ */
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Make an HTTP request with retry logic
+ */
+async function request(endpoint, params = {}) {
+  const query = querystring.stringify(params);
+  const path = `${BASE_PATH}${endpoint}?${query}`;
+  
+  let attempt = 0;
+
+  while (attempt <= RETRY_CONFIG.maxRetries) {
+    try {
+      return await doRequest(path);
+    } catch (error) {
+      if (error instanceof SemanticScholarError && error.statusCode === 429) {
+        attempt++;
+        if (attempt > RETRY_CONFIG.maxRetries) throw error;
+        
+        // Use Retry-After header if available, else exponential backoff
+        const delay = error.retryAfter 
+          ? parseInt(error.retryAfter, 10) * 1000 
+          : Math.min(RETRY_CONFIG.maxDelay, RETRY_CONFIG.baseDelay * Math.pow(2, attempt - 1));
+        
+        // console.error(`[S2] Rate limited. Retrying in ${delay}ms...`);
+        await sleep(delay);
+        continue;
+      }
+      throw error;
+    }
+  }
+}
+
+function doRequest(path) {
+  return new Promise((resolve, reject) => {
+    const options = {
+      hostname: BASE_HOST,
+      path: path,
+      method: 'GET',
+      headers: {
+        'User-Agent': 'WTF-P/0.4.0 (citation-expert)',
+      }
+    };
+
+    if (API_KEY) {
+      options.headers['x-api-key'] = API_KEY;
+    }
+
+    const req = https.request(options, (res) => {
+      let data = '';
+
+      res.on('data', (chunk) => data += chunk);
+
+      res.on('end', () => {
+        if (res.statusCode === 429) {
+          const retryAfter = res.headers['retry-after'];
+          return reject(new SemanticScholarError('Rate limit exceeded', 429, retryAfter));
+        }
+
+        if (res.statusCode >= 400) {
+          return reject(new SemanticScholarError(`API Error: ${res.statusCode} ${data}`, res.statusCode));
+        }
+
+        try {
+          const json = JSON.parse(data);
+          resolve(json);
+        } catch (e) {
+          reject(new Error(`Failed to parse response: ${e.message}`));
+        }
+      });
+    });
+
+    req.on('error', (e) => reject(new Error(`Request failed: ${e.message}`)));
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error('Request timed out'));
+    });
+    
+    // Set a reasonable timeout (10s)
+    req.setTimeout(10000);
+    req.end();
+  });
+}
+
+/**
+ * Search for papers
+ * @param {string} query 
+ * @param {Object} options 
+ */
+async function search(query, options = {}) {
+  const limit = Math.min(options.limit || 10, 100);
+  const fields = options.fields || [
+    'paperId', 'externalIds', 'title', 'abstract', 'venue', 'year', 
+    'citationCount', 'influentialCitationCount', 'authors', 
+    'publicationTypes', 'openAccessPdf'
+  ];
+
+  const params = {
+    query,
+    limit,
+    fields: fields.join(',')
+  };
+
+  if (options.year) params.year = options.year;
+
+  const response = await request('/paper/search', params);
+  return response.data || [];
+}
+
+/**
+ * Get paper by ID
+ * @param {string} id - S2 PaperId, DOI, ArXivId, etc.
+ * @param {string[]} fields 
+ */
+async function getPaper(id, fields = []) {
+  const defaultFields = [
+    'paperId', 'externalIds', 'title', 'abstract', 'venue', 'year', 
+    'citationCount', 'influentialCitationCount', 'authors', 
+    'publicationTypes', 'openAccessPdf'
+  ];
+  
+  const params = {
+    fields: (fields.length > 0 ? fields : defaultFields).join(',')
+  };
+
+  return await request(`/paper/${id}`, params);
+}
+
+/**
+ * Get citations for a paper
+ * @param {string} paperId 
+ * @param {number} limit 
+ */
+async function getCitations(paperId, limit = 20) {
+  const params = {
+    limit,
+    fields: 'title,year,citationCount,authors' // Minimal fields for citations
+  };
+  
+  const response = await request(`/paper/${paperId}/citations`, params);
+  return response.data || [];
+}
+
+module.exports = {
+  search,
+  getPaper,
+  getCitations,
+  SemanticScholarError
+};

package/bin/lib/utils.js

@@ -62,17 +62,25 @@ function isValidPath(inputPath) {
 }
 
 /**
- * Get the Claude config directory (respects CLAUDE_CONFIG_DIR env var)
+ * Get the configuration directory for a specific vendor
  */
-function getClaudeDir(explicitConfigDir, isGlobal = true) {
+function getVendorDir(vendor, explicitConfigDir, isGlobal = true) {
   if (!isGlobal) {
-    return path.join(process.cwd(), '.claude');
+    return path.join(process.cwd(), `.${vendor}`);
   }
 
+  const envVar = `${vendor.toUpperCase()}_CONFIG_DIR`;
   const configDir = normalizePath(explicitConfigDir) ||
-                   normalizePath(process.env.CLAUDE_CONFIG_DIR);
+                   normalizePath(process.env[envVar]);
 
-  return configDir || path.join(os.homedir(), '.claude');
+  return configDir || path.join(os.homedir(), `.${vendor}`);
+}
+
+/**
+ * Get the Claude config directory (respects CLAUDE_CONFIG_DIR env var)
+ */
+function getClaudeDir(explicitConfigDir, isGlobal = true) {
+  return getVendorDir('claude', explicitConfigDir, isGlobal);
 }
 
 /**
@@ -109,6 +117,9 @@ function readInstalledVersion(claudeDir) {
  * Write version tracking file
  */
 function writeVersionFile(claudeDir, version, installedFiles) {
+  if (!fs.existsSync(claudeDir)) {
+    fs.mkdirSync(claudeDir, { recursive: true });
+  }
   const versionFile = path.join(claudeDir, VERSION_FILE);
   const data = {
     version,
@@ -144,47 +155,56 @@ function simpleChecksum(filePath) {
 /**
  * Detect installation state
  */
-function detectInstallation(claudeDir) {
+function detectInstallation(vendorDir) {
   const result = {
     hasCommands: false,
-    hasSkill: false,
+    hasWorkflows: false,
+    hasSkills: false,
     version: null,
     partial: false,
     corrupt: false,
     commandFiles: [],
+    workflowFiles: [],
     skillFiles: []
   };
 
-  const commandsDir = path.join(claudeDir, 'commands', 'wtfp');
-  const skillDir = path.join(claudeDir, 'write-the-f-paper');
+  const commandsDir = path.join(vendorDir, 'commands', 'wtfp');
+  const workflowsDir = path.join(vendorDir, 'write-the-f-paper');
+  const skillsDir = path.join(vendorDir, 'skills', 'wtfp');
 
   result.hasCommands = fs.existsSync(commandsDir);
-  result.hasSkill = fs.existsSync(skillDir);
+  result.hasWorkflows = fs.existsSync(workflowsDir);
+  result.hasSkills = fs.existsSync(skillsDir);
 
   if (result.hasCommands) {
     result.commandFiles = collectFiles(commandsDir);
   }
-  if (result.hasSkill) {
-    result.skillFiles = collectFiles(skillDir);
+  if (result.hasWorkflows) {
+    result.workflowFiles = collectFiles(workflowsDir);
+  }
+  if (result.hasSkills) {
+    result.skillFiles = collectFiles(skillsDir);
   }
 
   // Read version info
-  const versionData = readInstalledVersion(claudeDir);
+  const versionData = readInstalledVersion(vendorDir);
   if (versionData) {
     result.version = versionData.version;
     result.corrupt = versionData.corrupt || false;
 
-    // Check for partial install (version file exists but missing dirs)
+    // Check for partial install
     if (!versionData.corrupt) {
       const expectedHasCommands = versionData.manifest?.some(f => f.path.includes('commands/wtfp'));
-      const expectedHasSkill = versionData.manifest?.some(f => f.path.includes('write-the-f-paper'));
+      const expectedHasWorkflows = versionData.manifest?.some(f => f.path.includes('write-the-f-paper'));
+      const expectedHasSkills = versionData.manifest?.some(f => f.path.includes('skills/wtfp'));
 
       if ((expectedHasCommands && !result.hasCommands) ||
-          (expectedHasSkill && !result.hasSkill)) {
+          (expectedHasWorkflows && !result.hasWorkflows) ||
+          (expectedHasSkills && !result.hasSkills)) {
         result.partial = true;
       }
     }
-  } else if (result.hasCommands || result.hasSkill) {
+  } else if (result.hasCommands || result.hasWorkflows || result.hasSkills) {
     // Files exist but no version file - legacy install
     result.version = 'legacy';
   }