@iservu-inc/adf-cli 0.1.6 → 0.2.0

package/lib/frameworks/interviewer.js

@@ -0,0 +1,447 @@
+const fs = require('fs-extra');
+const path = require('path');
+const inquirer = require('inquirer');
+const chalk = require('chalk');
+const { getQuestionsForFramework } = require('./questions');
+const ProgressTracker = require('./progress-tracker');
+const AnswerQualityAnalyzer = require('./answer-quality-analyzer');
+
+/**
+ * Conversational AI Interviewer
+ * Guides users through framework-specific questions with intelligent follow-ups
+ * Supports real-time progress tracking and resume capability
+ */
+
+class Interviewer {
+  constructor(framework, projectPath, existingSession = null) {
+    this.framework = framework;
+    this.projectPath = projectPath;
+
+    if (existingSession) {
+      // Resuming existing session
+      this.sessionId = existingSession.sessionId;
+      this.sessionPath = existingSession.sessionPath;
+      this.answers = existingSession.progress.answers || {};
+      this.transcript = existingSession.progress.transcript || [];
+      this.isResuming = true;
+    } else {
+      // New session
+      this.sessionId = this.generateSessionId();
+      this.sessionPath = path.join(projectPath, '.adf', 'sessions', this.sessionId);
+      this.answers = {};
+      this.transcript = [];
+      this.isResuming = false;
+    }
+
+    this.progressTracker = null;
+  }
+
+  generateSessionId() {
+    const now = new Date();
+    const timestamp = now.toISOString().replace(/:/g, '-').split('.')[0];
+    return `${timestamp}_${this.framework}`;
+  }
+
+  async start() {
+    console.log(chalk.cyan.bold('\n🤖 AI-Guided Requirements Gathering\n'));
+    console.log(chalk.gray(`I'll guide you through questions to create a comprehensive ${this.getFrameworkName()} document.\n`));
+    console.log(chalk.gray(`Session: ${this.sessionId}`));
+    console.log(chalk.gray(`Files will be saved to: .adf/sessions/${this.sessionId}/\n`));
+
+    // Create session directory
+    await fs.ensureDir(this.sessionPath);
+    await fs.ensureDir(path.join(this.sessionPath, 'qa-responses'));
+    await fs.ensureDir(path.join(this.sessionPath, 'outputs'));
+
+    // Get questions for framework
+    const questions = getQuestionsForFramework(this.framework);
+
+    // Group questions into blocks by phase
+    const questionBlocks = this.groupQuestionsIntoBlocks(questions);
+
+    // Initialize progress tracker
+    this.progressTracker = new ProgressTracker(this.sessionPath, questionBlocks.length, this.framework);
+    const isResumable = await this.progressTracker.initialize();
+
+    if (isResumable && this.isResuming) {
+      console.log(chalk.green('\n✓ Resuming previous session\n'));
+      const resumeInfo = this.progressTracker.getResumeInfo();
+      console.log(chalk.gray(`Last updated: ${new Date(resumeInfo.lastUpdated).toLocaleString()}`));
+      console.log(chalk.gray(`Progress: ${resumeInfo.completedBlocks}/${resumeInfo.totalBlocks} blocks | ${resumeInfo.totalQuestionsAnswered} questions\n`));
+    }
+
+    console.log(chalk.cyan(`\nℹ️  Total question blocks: ${questionBlocks.length}\n`));
+    console.log(chalk.gray('━'.repeat(60)) + '\n');
+
+    // Interview each block
+    for (let i = 0; i < questionBlocks.length; i++) {
+      const block = questionBlocks[i];
+
+      // Show block preview
+      const shouldAnswer = await this.showBlockPreview(block, i + 1, questionBlocks.length);
+
+      if (shouldAnswer === 'skip') {
+        console.log(chalk.yellow(`\n⏭️  Skipped: ${block.title}\n`));
+        await this.progressTracker.skipBlock(i + 1, block.title);
+        this.transcript.push({
+          type: 'block-skipped',
+          block: block.title,
+          timestamp: new Date().toISOString()
+        });
+        continue;
+      }
+
+      if (shouldAnswer === 'quit') {
+        console.log(chalk.yellow('\n👋 Interview ended early. Partial progress saved.\n'));
+        await this.progressTracker.saveCheckpoint('User ended interview early');
+        break;
+      }
+
+      // Track block start
+      await this.progressTracker.startBlock(i + 1, block.title);
+
+      // Ask questions in this block
+      const questionsAnswered = await this.askBlockQuestions(block, i + 1, questionBlocks.length);
+
+      // Track block complete
+      await this.progressTracker.completeBlock(i + 1, block.title, questionsAnswered);
+
+      // Save block answers
+      await this.saveBlockAnswers(block);
+    }
+
+    // Generate framework outputs
+    await this.generateOutputs();
+
+    // Save transcript
+    await this.saveTranscript();
+
+    // Save session metadata
+    await this.saveMetadata();
+
+    // Mark session as complete
+    await this.progressTracker.complete();
+
+    console.log(chalk.green.bold('\n✨ Requirements gathering complete!\n'));
+    console.log(chalk.cyan(`📁 Session saved to: .adf/sessions/${this.sessionId}/\n`));
+
+    return this.sessionPath;
+  }
+
+  getFrameworkName() {
+    const names = {
+      rapid: 'Product Requirement Prompt (PRP)',
+      balanced: 'Specification + Implementation Plan',
+      comprehensive: 'BMAD Framework Document'
+    };
+    return names[this.framework] || 'Requirements Document';
+  }
+
+  groupQuestionsIntoBlocks(questions) {
+    const blocks = {};
+
+    questions.forEach(q => {
+      if (!blocks[q.phase]) {
+        blocks[q.phase] = {
+          phase: q.phase,
+          title: this.formatPhaseTitle(q.phase),
+          questions: []
+        };
+      }
+      blocks[q.phase].questions.push(q);
+    });
+
+    // Sort questions within each block by importance (priority questions first)
+    Object.values(blocks).forEach(block => {
+      block.questions.sort((a, b) => {
+        // Priority order: questions with followUpTriggers come first (more critical)
+        const aPriority = a.followUpTriggers ? 0 : 1;
+        const bPriority = b.followUpTriggers ? 0 : 1;
+        return aPriority - bPriority;
+      });
+    });
+
+    return Object.values(blocks);
+  }
+
+  formatPhaseTitle(phase) {
+    return phase
+      .split('-')
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ');
+  }
+
+  async showBlockPreview(block, current, total) {
+    console.log(chalk.cyan.bold(`📋 Block ${current} of ${total}: ${block.title}\n`));
+
+    // Show what this block covers
+    console.log(chalk.gray('This block covers:'));
+    const topQuestions = block.questions.slice(0, 3);
+    topQuestions.forEach(q => {
+      console.log(chalk.gray(`  • ${q.text}`));
+    });
+
+    if (block.questions.length > 3) {
+      console.log(chalk.gray(`  • ...and ${block.questions.length - 3} more questions\n`));
+    } else {
+      console.log('');
+    }
+
+    // Show example
+    if (topQuestions[0]) {
+      console.log(chalk.gray('💡 Example good answer:'));
+      console.log(chalk.green(`   "${topQuestions[0].goodExample}"\n`));
+    }
+
+    // Ask if they want to answer this block
+    const { action } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'action',
+        message: 'How would you like to proceed?',
+        choices: [
+          { name: 'Answer this block', value: 'answer' },
+          { name: 'Skip this block', value: 'skip' },
+          { name: 'Skip remaining blocks and finish', value: 'quit' }
+        ],
+        default: 'answer'
+      }
+    ]);
+
+    console.log(chalk.gray('\n' + '━'.repeat(60)) + '\n');
+
+    return action;
+  }
+
+  async askBlockQuestions(block, currentBlock, totalBlocks) {
+    const blockAnswers = {};
+    let questionsAnswered = 0;
+
+    for (let i = 0; i < block.questions.length; i++) {
+      const question = block.questions[i];
+      const answer = await this.askQuestion(question, i + 1, block.questions.length, currentBlock, totalBlocks);
+
+      if (answer === null) {
+        // User skipped remaining questions in block
+        break;
+      }
+
+      blockAnswers[question.id] = answer;
+      this.answers[question.id] = answer;
+      questionsAnswered++;
+
+      // Log to transcript
+      this.transcript.push({
+        type: 'question-answer',
+        question: question.text,
+        answer: answer,
+        questionId: question.id,
+        timestamp: new Date().toISOString()
+      });
+    }
+
+    return questionsAnswered;
+  }
+
+  async askQuestion(question, current, totalInBlock, currentBlock, totalBlocks) {
+    console.log(chalk.cyan(`Question ${current}/${totalInBlock}`) + chalk.gray(` (Block ${currentBlock}/${totalBlocks})`) + '\n');
+    console.log(chalk.white.bold(question.text) + '\n');
+
+    // Show guidance
+    console.log(chalk.gray(`💡 ${question.guidance}`));
+    console.log(chalk.green(`   ✓ Good: ${question.goodExample}`));
+    console.log(chalk.red(`   ✗ Bad: ${question.badExample}\n`));
+
+    // Get answer
+    const { answer } = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'answer',
+        message: 'Your answer:',
+        validate: (input) => {
+          if (!input || input.trim().length === 0) {
+            return 'Please provide an answer or type "skip" to skip remaining questions in this block';
+          }
+          return true;
+        }
+      }
+    ]);
+
+    if (answer.toLowerCase() === 'skip') {
+      return null; // Signal to skip remaining questions
+    }
+
+    // Analyze answer quality
+    const qualityMetrics = AnswerQualityAnalyzer.analyze(answer, question);
+
+    // Show quality feedback
+    const feedback = AnswerQualityAnalyzer.getFeedback(qualityMetrics);
+    if (feedback) {
+      console.log(chalk.cyan(`${feedback}`));
+    }
+
+    // Track answer with quality metrics
+    await this.progressTracker.answerQuestion(question.id, question.text, answer, qualityMetrics);
+
+    // Check if answer is comprehensive enough to skip follow-ups
+    if (qualityMetrics.canSkipFollowUps) {
+      console.log(chalk.green('\n✓ Saved\n'));
+      return answer;
+    }
+
+    // Check if answer needs follow-up
+    const followUp = this.determineFollowUp(question, answer);
+
+    if (followUp) {
+      console.log(chalk.yellow(`\n🤖 ${followUp.message}\n`));
+
+      const { followUpAnswer } = await inquirer.prompt([
+        {
+          type: 'input',
+          name: 'followUpAnswer',
+          message: followUp.question
+        }
+      ]);
+
+      if (followUpAnswer && followUpAnswer.trim()) {
+        // Combine answers
+        const combined = `${answer} | Follow-up: ${followUpAnswer}`;
+
+        // Re-analyze combined answer
+        const combinedMetrics = AnswerQualityAnalyzer.analyze(combined, question);
+        await this.progressTracker.answerQuestion(question.id, question.text, combined, combinedMetrics);
+
+        console.log(chalk.green('\n✓ Saved\n'));
+        return combined;
+      }
+    }
+
+    console.log(chalk.green('\n✓ Saved\n'));
+    return answer;
+  }
+
+  determineFollowUp(question, answer) {
+    if (!question.followUpTriggers) return null;
+
+    const triggers = question.followUpTriggers;
+    const lowerAnswer = answer.toLowerCase();
+
+    // Check for vague answers
+    if (triggers.vague) {
+      const hasVagueWord = triggers.vague.some(word => lowerAnswer.includes(word));
+      if (hasVagueWord && answer.split(' ').length < 5) {
+        return {
+          message: "That's a bit vague. Let me ask a more specific question:",
+          question: "Can you provide more specific details? (e.g., what technology, what platform, what specific functionality)"
+        };
+      }
+    }
+
+    // Check for missing technology
+    if (triggers.missingTech && typeof triggers.missingTech === 'function') {
+      if (triggers.missingTech(answer)) {
+        return {
+          message: "I notice you didn't mention the technology stack.",
+          question: "What framework, language, or technology will you use for this?"
+        };
+      }
+    }
+
+    // Check for missing platform
+    if (triggers.missingPlatform && typeof triggers.missingPlatform === 'function') {
+      if (triggers.missingPlatform(answer)) {
+        return {
+          message: "I'm not clear on the platform.",
+          question: "Is this for web, mobile, desktop, API, or something else?"
+        };
+      }
+    }
+
+    return null;
+  }
+
+  async saveBlockAnswers(block) {
+    const fileName = `${block.phase}.md`;
+    const filePath = path.join(this.sessionPath, 'qa-responses', fileName);
+
+    let content = `# ${block.title}\n\n`;
+    content += `**Block:** ${block.phase}\n`;
+    content += `**Questions answered:** ${block.questions.filter(q => this.answers[q.id]).length}/${block.questions.length}\n`;
+    content += `**Timestamp:** ${new Date().toISOString()}\n\n`;
+    content += `---\n\n`;
+
+    block.questions.forEach(q => {
+      if (this.answers[q.id]) {
+        content += `## ${q.text}\n\n`;
+        content += `**Answer:** ${this.answers[q.id]}\n\n`;
+        content += `---\n\n`;
+      }
+    });
+
+    await fs.writeFile(filePath, content, 'utf-8');
+  }
+
+  async saveTranscript() {
+    const filePath = path.join(this.sessionPath, '_transcript.md');
+
+    let content = `# Interview Transcript\n\n`;
+    content += `**Session:** ${this.sessionId}\n`;
+    content += `**Framework:** ${this.getFrameworkName()}\n`;
+    content += `**Total Answers:** ${Object.keys(this.answers).length}\n`;
+    content += `**Date:** ${new Date().toISOString()}\n\n`;
+    content += `---\n\n`;
+
+    this.transcript.forEach((entry, i) => {
+      if (entry.type === 'question-answer') {
+        content += `## Q${i + 1}: ${entry.question}\n\n`;
+        content += `**Answer:** ${entry.answer}\n\n`;
+        content += `**Timestamp:** ${entry.timestamp}\n\n`;
+        content += `---\n\n`;
+      } else if (entry.type === 'block-skipped') {
+        content += `## [SKIPPED] ${entry.block}\n\n`;
+        content += `**Timestamp:** ${entry.timestamp}\n\n`;
+        content += `---\n\n`;
+      }
+    });
+
+    await fs.writeFile(filePath, content, 'utf-8');
+  }
+
+  async saveMetadata() {
+    const metadata = {
+      sessionId: this.sessionId,
+      framework: this.framework,
+      frameworkName: this.getFrameworkName(),
+      startedAt: this.transcript[0]?.timestamp || new Date().toISOString(),
+      completedAt: new Date().toISOString(),
+      totalQuestions: Object.keys(this.answers).length,
+      answers: this.answers,
+      projectPath: this.projectPath
+    };
+
+    const filePath = path.join(this.sessionPath, '_metadata.json');
+    await fs.writeJson(filePath, metadata, { spaces: 2 });
+  }
+
+  async generateOutputs() {
+    const outputsPath = path.join(this.sessionPath, 'outputs');
+
+    // Import output generators
+    const generators = require('./output-generators');
+
+    console.log(chalk.cyan('\n📝 Generating framework documents...\n'));
+
+    if (this.framework === 'rapid') {
+      await generators.generatePRP(this.answers, outputsPath);
+      console.log(chalk.green('✓ Generated: prp.md\n'));
+    } else if (this.framework === 'balanced') {
+      await generators.generateBalanced(this.answers, outputsPath);
+      console.log(chalk.green('✓ Generated: constitution.md, specification.md, plan.md, tasks.md\n'));
+    } else if (this.framework === 'comprehensive') {
+      await generators.generateBMAD(this.answers, outputsPath);
+      console.log(chalk.green('✓ Generated: prd.md, architecture.md, stories.md\n'));
+    }
+  }
+}
+
+module.exports = Interviewer;