wtf-p 0.2.0 → 0.4.0

package/README.md

@@ -2,14 +2,18 @@
 
 # WTF-P
 
+**Write The Freaking...**
+- **P**aper
+- **P**roposal
+- **P**resentation
+- **P**oster
+
 **Context engineering for academic writing with Claude Code.**
 
 ```bash
 npx wtf-p
 ```
 
-*Write The Freaking Paper. Finally.*
-
 </div>
 
 ---
@@ -209,6 +213,24 @@ The mapping phase analyzes:
 
 ---
 
+## Citation Expert (v0.4.0)
+
+WTF-P includes a specialized tiered pipeline for bibliography management.
+
+```bash
+/wtfp:analyze-bib      # Deep analysis of impact (seminal vs rising)
+/wtfp:research-gap     # Intent-aware search (seminal/recent)
+/wtfp:check-refs       # Auto-suggest missing citations
+```
+
+Capabilities:
+- **Tiered Search:** Integrated Semantic Scholar, SerpAPI (Google Scholar), and CrossRef.
+- **Impact Ranking:** Automatically scores papers by citations, velocity, and venue prestige.
+- **Deduplication:** universal anchoring via DOI and Scholar Cluster IDs.
+- **Provenance:** Entries track their metadata source and verification status.
+
+---
+
 ## Command Reference
 
 ### Setup

package/bin/commands/doctor.js

@@ -0,0 +1,100 @@
+const fs = require('fs');
+const path = require('path');
+const { getClaudeDir, normalizePath, getPathLabel, detectInstallation } = require('../lib/utils');
+
+async function runDoctor(options) {
+  const { out, explicitConfigDir } = options;
+  const c = out.colors;
+
+  out.log(`  ${c.yellow('WTF-P Installation Doctor')}\n`);
+
+  const issues = [];
+  const checks = [];
+
+  // Check 1: Node.js version
+  const nodeVersion = process.version;
+  const nodeMajor = parseInt(nodeVersion.slice(1).split('.')[0], 10);
+  if (nodeMajor < 16) {
+    issues.push(`Node.js ${nodeVersion} is below minimum (16.7.0)`);
+    checks.push({ name: 'Node.js version', status: 'fail', detail: nodeVersion });
+  } else {
+    checks.push({ name: 'Node.js version', status: 'pass', detail: nodeVersion });
+  }
+
+  // Check 2: Claude directory exists
+  const globalDir = getClaudeDir(explicitConfigDir, true);
+  if (fs.existsSync(globalDir)) {
+    checks.push({ name: 'Claude config directory', status: 'pass', detail: getPathLabel(globalDir, true) });
+  } else {
+    checks.push({ name: 'Claude config directory', status: 'warn', detail: 'Does not exist (will be created on install)' });
+  }
+
+  // Check 3: Write permissions
+  const testDir = globalDir.replace(/\.claude$/, '.claude-test-' + Date.now());
+  try {
+    fs.mkdirSync(testDir, { recursive: true });
+    fs.writeFileSync(path.join(testDir, 'test'), 'test');
+    fs.rmSync(testDir, { recursive: true });
+    checks.push({ name: 'Write permissions', status: 'pass', detail: 'Can write to config directory' });
+  } catch (err) {
+    issues.push(`Cannot write to ${getPathLabel(globalDir, true)}: ${err.message}`);
+    checks.push({ name: 'Write permissions', status: 'fail', detail: err.message });
+  }
+
+  // Check 4: Installation state
+  const detection = detectInstallation(globalDir);
+  if (detection.hasCommands || detection.hasWorkflows || detection.hasSkills) {
+    if (detection.partial) {
+      issues.push('Partial installation detected - some files are missing');
+      checks.push({ name: 'Installation integrity', status: 'warn', detail: 'Partial install' });
+    } else if (detection.corrupt) {
+      issues.push('Version file is corrupt - reinstall recommended');
+      checks.push({ name: 'Installation integrity', status: 'warn', detail: 'Corrupt version file' });
+    } else {
+      checks.push({ name: 'Installation integrity', status: 'pass', detail: `v${detection.version}` });
+    }
+  } else {
+    checks.push({ name: 'Installation integrity', status: 'info', detail: 'Not installed' });
+  }
+
+  // Check 5: CLAUDE_CONFIG_DIR env var
+  const configDirEnv = process.env.CLAUDE_CONFIG_DIR;
+  if (configDirEnv) {
+    const expanded = normalizePath(configDirEnv);
+    if (fs.existsSync(expanded)) {
+      checks.push({ name: 'CLAUDE_CONFIG_DIR', status: 'pass', detail: expanded });
+    } else {
+      issues.push(`CLAUDE_CONFIG_DIR points to non-existent path: ${configDirEnv}`);
+      checks.push({ name: 'CLAUDE_CONFIG_DIR', status: 'warn', detail: `${configDirEnv} (does not exist)` });
+    }
+  } else {
+    checks.push({ name: 'CLAUDE_CONFIG_DIR', status: 'info', detail: 'Not set (using default)' });
+  }
+
+  // Output results
+  for (const check of checks) {
+    let icon, color;
+    switch (check.status) {
+      case 'pass': icon = '✓'; color = c.green; break;
+      case 'fail': icon = '✗'; color = c.red; break;
+      case 'warn': icon = '⚠'; color = c.yellow; break;
+      default: icon = 'ℹ'; color = c.cyan;
+    }
+    out.log(`  ${color(icon)} ${check.name}: ${c.dim(check.detail)}`);
+  }
+
+  out.log('');
+
+  if (issues.length > 0) {
+    out.log(`  ${c.yellow('Issues found:')}`);
+    for (const issue of issues) {
+      out.log(`    ${c.yellow('•')} ${issue}`);
+    }
+    out.log('');
+    out.log(`  ${c.dim('Run')} ${c.cyan('npx wtf-p --global --force')} ${c.dim('to reinstall')}\n`);
+  } else {
+    out.log(`  ${c.green('No issues found!')}\n`);
+  }
+}
+
+module.exports = runDoctor;

package/bin/commands/install-logic.js

@@ -0,0 +1,231 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const MANIFEST = require('../lib/manifest');
+const { 
+  isValidPath, 
+  getClaudeDir, // Legacy support, will refactor
+  getPathLabel, 
+  getBackupPath, 
+  writeVersionFile, 
+  createRL, 
+  prompt 
+} = require('../lib/utils');
+
+/**
+ * Process file content with path replacement
+ */
+function processContent(srcPath, pathPrefix) {
+  if (srcPath.endsWith('.md') || srcPath.endsWith('.json')) {
+    let content = fs.readFileSync(srcPath, 'utf8');
+    return content.replace(/~\/\.claude\//g, pathPrefix);
+  }
+  return null;
+}
+
+/**
+ * Collect files from a manifest component
+ */
+function collectComponentFiles(component, destBase, files = []) {
+  if (!fs.existsSync(component.src)) return files;
+
+  function recurse(currentSrc, currentRel) {
+    const entries = fs.readdirSync(currentSrc, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      const srcPath = path.join(currentSrc, entry.name);
+      const relPath = path.join(currentRel, entry.name);
+      const destPath = path.join(destBase, component.dest, relPath);
+
+      if (entry.isDirectory()) {
+        recurse(srcPath, relPath);
+      } else {
+        files.push({ 
+          src: srcPath, 
+          dest: destPath, 
+          name: entry.name,
+          componentId: component.id 
+        });
+      }
+    }
+  }
+
+  recurse(component.src, '.');
+  return files;
+}
+
+/**
+ * Install files with conflict resolution
+ */
+async function installWithConflictResolution(files, pathPrefix, targetDir, options) {
+  const { out, hasForce, hasBackupAll, isInteractive, showExplanations } = options;
+  const c = out.colors;
+  const rl = createRL();
+  let globalChoice = null;
+  const stats = { installed: 0, skipped: 0, backed: 0 };
+
+  const existingFiles = files.filter(f => fs.existsSync(f.dest));
+
+  if (existingFiles.length > 0 && !hasForce && !hasBackupAll && isInteractive) {
+    const relPath = getPathLabel(targetDir, true);
+    out.log(`  ${c.yellow(`Found ${existingFiles.length} existing WTF-P file(s) in ${relPath}`)}
+`);
+
+    if (showExplanations) {
+      out.log(`  ${c.dim('For each file, choose:')}`);
+      out.log(`  ${c.dim('[o]verwrite - Replace with new version')}`);
+      out.log(`  ${c.dim('[s]kip      - Keep your existing file')}`);
+      out.log(`  ${c.dim('[b]ackup    - Save existing, then install new')}`);
+      out.log(`  ${c.dim('[a]ll       - Apply same choice to remaining')}\n`);
+    }
+  }
+
+  for (const file of files) {
+    const exists = fs.existsSync(file.dest);
+    const relDest = file.dest.replace(os.homedir(), '~').replace(process.cwd(), '.');
+
+    fs.mkdirSync(path.dirname(file.dest), { recursive: true });
+
+    if (exists && !hasForce && !hasBackupAll) {
+      let choice = globalChoice;
+
+      if (!choice && isInteractive) {
+        const answer = await prompt(rl,
+          `  ${c.yellow('?')} ${c.dim(relDest)} exists. [o]verwrite/[s]kip/[b]ackup/[a]ll: `
+        );
+
+        if (answer.startsWith('a')) {
+          const allAnswer = await prompt(rl,
+            `    Apply to all: [o]verwrite/[s]kip/[b]ackup: `
+          );
+          if (allAnswer.startsWith('o')) globalChoice = 'overwrite';
+          else if (allAnswer.startsWith('b')) globalChoice = 'backup';
+          else globalChoice = 'skip';
+          choice = globalChoice;
+        } else if (answer.startsWith('o')) {
+          choice = 'overwrite';
+        } else if (answer.startsWith('b')) {
+          choice = 'backup';
+        } else {
+          choice = 'skip';
+        }
+      } else if (!choice) {
+        choice = 'skip';
+      }
+
+      if (choice === 'skip') {
+        out.verbose(`  ${c.dim('○')} Skipped ${c.dim(relDest)}`);
+        stats.skipped++;
+        continue;
+      }
+
+      if (choice === 'backup') {
+        const backupPath = getBackupPath(file.dest);
+        fs.copyFileSync(file.dest, backupPath);
+        out.log(`  ${c.cyan('↻')} Backed up to ${c.dim(path.basename(backupPath))}`);
+        stats.backed++;
+      }
+    } else if (exists && hasBackupAll) {
+      const backupPath = getBackupPath(file.dest);
+      fs.copyFileSync(file.dest, backupPath);
+      out.verbose(`  ${c.cyan('↻')} Backed up ${c.dim(relDest)}`);
+      stats.backed++;
+    }
+
+    const content = processContent(file.src, pathPrefix);
+    if (content !== null) {
+      fs.writeFileSync(file.dest, content);
+    } else {
+      fs.copyFileSync(file.src, file.dest);
+    }
+
+    if (!exists) {
+      out.verbose(`  ${c.green('+')} ${c.dim(relDest)}`);
+    } else {
+      out.verbose(`  ${c.green('✓')} ${c.dim(relDest)}`);
+    }
+    stats.installed++;
+  }
+
+  rl.close();
+  return stats;
+}
+
+/**
+ * Main install logic
+ */
+async function install(isGlobal, isUpdate, options, pkg) {
+  const { out, explicitConfigDir, hasQuiet, onlyInstall, showExplanations } = options;
+  const c = out.colors;
+
+  // Use Claude vendor by default for now (can be passed as arg later)
+  const vendorConfig = MANIFEST.claude;
+  
+  // Resolve Target Directory using the Vendor Strategy
+  // TODO: Use getVendorDir generic
+  const targetDir = getClaudeDir(explicitConfigDir, isGlobal);
+  const locationLabel = getPathLabel(targetDir, isGlobal);
+
+  // Validate path
+  if (!isValidPath(targetDir)) {
+    out.error(`Invalid path: ${targetDir}`);
+    process.exit(1);
+  }
+
+  const pathPrefix = isGlobal
+    ? (explicitConfigDir ? `${targetDir}/` : `~/${vendorConfig.defaultDir}/`)
+    : `./${vendorConfig.defaultDir}/`;
+
+  if (!hasQuiet) {
+    out.log(`  Installing to ${c.cyan(locationLabel)}
+`);
+  }
+
+  // Collect files based on Manifest
+  const allFiles = [];
+
+  vendorConfig.components.forEach(component => {
+    // Check --only filters
+    if (onlyInstall !== 'all') {
+      const allowedIds = [onlyInstall];
+      // Legacy mapping: 'commands' includes 'skills'
+      if (onlyInstall === 'commands') allowedIds.push('skills');
+      
+      if (!allowedIds.includes(component.id)) {
+        return;
+      }
+    }
+    
+    // DEBUG LOG
+    // console.log(`Collecting: ${component.id} from ${component.src}`);
+    
+    collectComponentFiles(component, targetDir, allFiles);
+  });
+  
+  // DEBUG
+  // console.log(`Total files found: ${allFiles.length}`);
+
+  // Install with conflict resolution
+  const stats = await installWithConflictResolution(allFiles, pathPrefix, targetDir, options);
+
+  // Write version tracking file
+  writeVersionFile(targetDir, pkg.version, allFiles);
+
+  // Summary
+  if (!hasQuiet) {
+    out.log(`
+  ${c.green('Done!')} Installed: ${stats.installed}, Skipped: ${stats.skipped}, Backed up: ${stats.backed}
+
+  Run ${c.cyan('/wtfp:help')} in Claude Code to get started.
+`);
+
+    if (showExplanations && !isUpdate) {
+      out.log(`  ${c.yellow('Quick Start:')}`);
+      out.log(`    ${c.cyan('/wtfp:new-paper')}      Start a new academic paper`);
+      out.log(`    ${c.cyan('/wtfp:progress')}       Check your writing status`);
+      out.log(`    ${c.cyan('/wtfp:help')}           Show all commands\n`);
+    }
+  }
+}
+
+module.exports = install;

package/bin/commands/list.js

@@ -0,0 +1,88 @@
+const fs = require('fs');
+const path = require('path');
+const MANIFEST = require('../lib/manifest');
+const { collectComponentFiles } = require('./install-logic'); // Need to export this or copy logic
+
+// Re-implementing logic here to avoid circular dep if install-logic is messy
+// But better to export valid logic.
+
+/**
+ * Collect files from a manifest component
+ */
+function collectComponentFilesLocal(component, files = []) {
+  if (!fs.existsSync(component.src)) return files;
+
+  function recurse(currentSrc, currentRel) {
+    const entries = fs.readdirSync(currentSrc, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      const srcPath = path.join(currentSrc, entry.name);
+      const relPath = path.join(currentRel, entry.name);
+      // For listing, we just want the relative destination path
+      const destPath = path.join(component.dest, relPath);
+
+      if (entry.isDirectory()) {
+        recurse(srcPath, relPath);
+      } else {
+        files.push({ 
+          src: srcPath, 
+          path: destPath, // display path
+          type: component.id
+        });
+      }
+    }
+  }
+
+  recurse(component.src, '.');
+  return files;
+}
+
+function showList(options) {
+  const { out, hasQuiet, onlyInstall } = options;
+  const c = out.colors;
+  
+  // Use Claude by default
+  const vendorConfig = MANIFEST.claude;
+
+  const files = [];
+
+  vendorConfig.components.forEach(component => {
+    if (onlyInstall !== 'all') {
+      if (onlyInstall !== component.id) {
+         if (onlyInstall === 'commands' && component.id === 'skills') {
+           // Allow
+         } else {
+           return;
+         }
+      }
+    }
+    collectComponentFilesLocal(component, files);
+  });
+
+  if (!hasQuiet) {
+    out.log(`  ${c.yellow('Files to install:')}\n`);
+  }
+
+  // Group by component
+  const groups = {};
+  files.forEach(f => {
+    if (!groups[f.type]) groups[f.type] = [];
+    groups[f.type].push(f);
+  });
+
+  Object.keys(groups).forEach(type => {
+    const groupFiles = groups[type];
+    out.log(`  ${c.cyan(type.charAt(0).toUpperCase() + type.slice(1))} (${groupFiles.length} files):`);
+    for (const f of groupFiles.slice(0, 10)) {
+      out.log(`    ${c.dim(f.path)}`);
+    }
+    if (groupFiles.length > 10) {
+      out.log(`    ${c.dim(`... and ${groupFiles.length - 10} more`)}`);
+    }
+    out.log('');
+  });
+
+  out.log(`  Total: ${files.length} files\n`);
+}
+
+module.exports = showList;

package/bin/commands/status.js

@@ -0,0 +1,85 @@
+const fs = require('fs');
+const { execSync } = require('child_process');
+const { getClaudeDir, detectInstallation, getPathLabel } = require('../lib/utils');
+
+async function showStatus(options, pkg) {
+  const { out, explicitConfigDir, hasQuiet } = options;
+  const c = out.colors;
+
+  if (!hasQuiet) {
+    // Note: banner should be handled by the main entry point or passed in
+  }
+
+  const locations = [];
+
+  // Check global
+  const globalDir = getClaudeDir(explicitConfigDir, true);
+  const globalDetection = detectInstallation(globalDir);
+  locations.push({
+    label: 'Global',
+    path: globalDir,
+    pathLabel: getPathLabel(globalDir, true),
+    ...globalDetection
+  });
+
+  // Check local if different
+  const localDir = getClaudeDir(null, false);
+  if (localDir !== globalDir) {
+    const localDetection = detectInstallation(localDir);
+    locations.push({
+      label: 'Local',
+      path: localDir,
+      pathLabel: getPathLabel(localDir, false),
+      ...localDetection
+    });
+  }
+
+  out.log(`  ${c.yellow('WTF-P Installation Status')}\n`);
+
+  for (const loc of locations) {
+    const installed = loc.hasCommands || loc.hasWorkflows || loc.hasSkills;
+
+    out.log(`  ${c.cyan(loc.label)} ${c.dim(`(${loc.pathLabel})`)}`);
+
+    if (!installed) {
+      out.log(`    ${c.dim('Not installed')}\n`);
+      continue;
+    }
+
+    // Version
+    if (loc.version) {
+      const versionLabel = loc.version === 'legacy' ? 'legacy (pre-0.2.0)' : loc.version;
+      out.log(`    Version: ${c.green(versionLabel)}`);
+    }
+
+    // Components
+    const components = [];
+    if (loc.hasCommands) components.push(`commands (${loc.commandFiles.length} files)`);
+    if (loc.hasWorkflows) components.push(`workflows (${loc.workflowFiles.length} files)`);
+    if (loc.hasSkills) components.push(`skills (${loc.skillFiles.length} files)`);
+    out.log(`    Installed: ${components.join(', ')}`);
+
+    // Warnings
+    if (loc.partial) {
+      out.log(`    ${c.yellow('⚠ Partial installation detected')}`);
+    }
+    if (loc.corrupt) {
+      out.log(`    ${c.red('⚠ Corrupt version file')}`);
+    }
+
+    out.log('');
+  }
+
+  // Check for updates
+  try {
+    const latest = execSync('npm view wtf-p version 2>/dev/null', { encoding: 'utf8' }).trim();
+    if (latest && latest !== pkg.version) {
+      out.log(`  ${c.yellow('Update available:')} ${pkg.version} → ${c.green(latest)}`);
+      out.log(`  Run: ${c.cyan('npx wtf-p update --global')}\n`);
+    }
+  } catch {
+    // Ignore
+  }
+}
+
+module.exports = showStatus;

package/bin/commands/update.js

@@ -0,0 +1,50 @@
+const { getClaudeDir, detectInstallation, getPathLabel } = require('../lib/utils');
+
+async function runUpdate(options, pkg, installFunc) {
+  const { out, explicitConfigDir, hasGlobal, hasLocal } = options;
+  const c = out.colors;
+
+  out.log(`  ${c.yellow('Checking for updates...')}\n`);
+
+  // Find installed location
+  const globalDir = getClaudeDir(explicitConfigDir, true);
+  const localDir = getClaudeDir(null, false);
+
+  let targetDir = null;
+  let isGlobal = true;
+
+  const globalDetection = detectInstallation(globalDir);
+  const localDetection = detectInstallation(localDir);
+
+  if (hasGlobal || (!hasLocal && (globalDetection.hasCommands || globalDetection.hasWorkflows || globalDetection.hasSkills))) {
+    targetDir = globalDir;
+    isGlobal = true;
+  } else if (hasLocal || (localDetection.hasCommands || localDetection.hasWorkflows || localDetection.hasSkills)) {
+    targetDir = localDir;
+    isGlobal = false;
+  }
+
+  if (!targetDir) {
+    out.log(`  ${c.yellow('No existing installation found.')}`);
+    out.log(`  Run ${c.cyan('npx wtf-p --global')} to install.\n`);
+    return;
+  }
+
+  const detection = isGlobal ? globalDetection : localDetection;
+  const currentVersion = detection.version === 'legacy' ? '0.0.0' : detection.version;
+
+  out.log(`  Current: ${c.dim(`v${currentVersion}`)} in ${c.dim(getPathLabel(targetDir, isGlobal))}`);
+  out.log(`  Package: ${c.dim(`v${pkg.version}`)}`);
+
+  if (pkg.version === currentVersion) {
+    out.log(`\n  ${c.green('Already up to date!')}\n`);
+    return;
+  }
+
+  out.log(`\n  ${c.cyan('Updating...')}\n`);
+
+  // Run install with backup
+  await installFunc(isGlobal, true);
+}
+
+module.exports = runUpdate;