@iservu-inc/adf-cli 0.3.6 → 0.4.12

package/lib/learning/skip-tracker.js

@@ -0,0 +1,260 @@
+const { v4: uuidv4 } = require('uuid');
+const storage = require('./storage');
+
+/**
+ * Skip Tracker - Records user skip and answer behavior
+ *
+ * Tracks:
+ * - Questions skipped manually
+ * - Questions skipped by filtering
+ * - Answer metadata (length, quality scores)
+ * - Time spent on questions
+ */
+
+class SkipTracker {
+  constructor(projectPath, sessionMetadata = {}) {
+    this.projectPath = projectPath;
+    this.sessionId = uuidv4();
+    this.sessionMetadata = sessionMetadata;
+    this.sessionData = {
+      sessionId: this.sessionId,
+      timestamp: new Date().toISOString(),
+      projectType: sessionMetadata.projectType || 'unknown',
+      frameworks: sessionMetadata.frameworks || [],
+      languages: sessionMetadata.languages || [],
+      skips: [],
+      answers: []
+    };
+    this.questionStartTimes = {};
+  }
+
+  /**
+   * Record when a question is shown to the user
+   * @param {string} questionId - Question identifier
+   */
+  startQuestion(questionId) {
+    this.questionStartTimes[questionId] = Date.now();
+  }
+
+  /**
+   * Get time spent on a question in seconds
+   * @param {string} questionId - Question identifier
+   * @returns {number} Time in seconds
+   */
+  getTimeSpent(questionId) {
+    if (!this.questionStartTimes[questionId]) {
+      return 0;
+    }
+    const elapsed = Date.now() - this.questionStartTimes[questionId];
+    return Math.round(elapsed / 100) / 10; // Round to 1 decimal
+  }
+
+  /**
+   * Record a skip event
+   * @param {Object} question - Question object
+   * @param {string} reason - 'manual' | 'filtered'
+   * @param {Object} metadata - Additional metadata
+   */
+  recordSkip(question, reason = 'manual', metadata = {}) {
+    const skipEvent = {
+      questionId: question.id,
+      text: question.text,
+      category: question.category || null,
+      phase: question.phase || null,
+      action: 'skipped',
+      reason,
+      timeViewed: this.getTimeSpent(question.id),
+      relevanceScore: question.relevance || null,
+      skipReason: question.skipReason || null,
+      ...metadata
+    };
+
+    this.sessionData.skips.push(skipEvent);
+  }
+
+  /**
+   * Record an answer event
+   * @param {Object} question - Question object
+   * @param {string} answer - User's answer
+   * @param {Object} metadata - Additional metadata (quality scores, etc.)
+   */
+  recordAnswer(question, answer, metadata = {}) {
+    const answerEvent = {
+      questionId: question.id,
+      text: question.text,
+      category: question.category || null,
+      phase: question.phase || null,
+      action: 'answered',
+      answerLength: answer.length,
+      wordCount: answer.split(/\s+/).filter(w => w.length > 0).length,
+      timeSpent: this.getTimeSpent(question.id),
+      qualityScore: metadata.qualityScore || null,
+      richness: metadata.richness || null,
+      relevanceScore: question.relevance || null,
+      ...metadata
+    };
+
+    this.sessionData.answers.push(answerEvent);
+  }
+
+  /**
+   * Record multiple filtered questions (bulk operation)
+   * @param {Array} filteredQuestions - Array of filtered question objects
+   */
+  recordFilteredQuestions(filteredQuestions) {
+    for (const question of filteredQuestions) {
+      this.recordSkip(question, 'filtered', {
+        filterReason: question.reason || 'Low relevance score'
+      });
+    }
+  }
+
+  /**
+   * Get session summary statistics
+   * @returns {Object} Session summary
+   */
+  getSessionSummary() {
+    return {
+      sessionId: this.sessionId,
+      timestamp: this.sessionData.timestamp,
+      projectType: this.sessionData.projectType,
+      frameworks: this.sessionData.frameworks,
+      totalSkips: this.sessionData.skips.length,
+      manualSkips: this.sessionData.skips.filter(s => s.reason === 'manual').length,
+      filteredSkips: this.sessionData.skips.filter(s => s.reason === 'filtered').length,
+      totalAnswers: this.sessionData.answers.length,
+      avgAnswerLength: this.sessionData.answers.length > 0
+        ? Math.round(this.sessionData.answers.reduce((sum, a) => sum + a.wordCount, 0) / this.sessionData.answers.length)
+        : 0
+    };
+  }
+
+  /**
+   * Save session data to storage
+   */
+  async saveSession() {
+    try {
+      // Save skip history
+      await storage.appendToLearningHistory(
+        this.projectPath,
+        'skip-history.json',
+        this.sessionData,
+        'sessions'
+      );
+
+      // Save answer history
+      const answerSessionData = {
+        sessionId: this.sessionId,
+        timestamp: this.sessionData.timestamp,
+        projectType: this.sessionData.projectType,
+        frameworks: this.sessionData.frameworks,
+        answers: this.sessionData.answers
+      };
+
+      await storage.appendToLearningHistory(
+        this.projectPath,
+        'answer-history.json',
+        answerSessionData,
+        'sessions'
+      );
+
+      // Update statistics
+      await storage.updateLearningStats(this.projectPath, {
+        totalSessions: (await storage.getLearningStats(this.projectPath)).totalSessions + 1,
+        totalSkips: (await storage.getLearningStats(this.projectPath)).totalSkips + this.sessionData.skips.length,
+        totalAnswers: (await storage.getLearningStats(this.projectPath)).totalAnswers + this.sessionData.answers.length
+      });
+
+      return true;
+    } catch (error) {
+      console.error('Error saving skip tracker session:', error.message);
+      return false;
+    }
+  }
+
+  /**
+   * Get current session data (for debugging/testing)
+   * @returns {Object} Current session data
+   */
+  getSessionData() {
+    return this.sessionData;
+  }
+}
+
+/**
+ * Helper function to analyze skip patterns from history
+ * @param {string} projectPath - Project root path
+ * @returns {Promise<Object>} Skip pattern analysis
+ */
+async function analyzeSkipPatterns(projectPath) {
+  const skipHistory = await storage.getSkipHistory(projectPath);
+
+  if (!skipHistory || !skipHistory.sessions || skipHistory.sessions.length === 0) {
+    return {
+      totalSessions: 0,
+      totalSkips: 0,
+      manualSkips: 0,
+      filteredSkips: 0,
+      mostSkippedQuestions: [],
+      mostSkippedCategories: []
+    };
+  }
+
+  // Count skips by question
+  const questionSkipCounts = {};
+  const categorySkipCounts = {};
+  let totalManualSkips = 0;
+  let totalFilteredSkips = 0;
+
+  for (const session of skipHistory.sessions) {
+    for (const skip of session.skips || []) {
+      // Count by question
+      if (!questionSkipCounts[skip.questionId]) {
+        questionSkipCounts[skip.questionId] = {
+          questionId: skip.questionId,
+          text: skip.text,
+          count: 0,
+          category: skip.category
+        };
+      }
+      questionSkipCounts[skip.questionId].count++;
+
+      // Count by category
+      if (skip.category) {
+        categorySkipCounts[skip.category] = (categorySkipCounts[skip.category] || 0) + 1;
+      }
+
+      // Count by reason
+      if (skip.reason === 'manual') {
+        totalManualSkips++;
+      } else if (skip.reason === 'filtered') {
+        totalFilteredSkips++;
+      }
+    }
+  }
+
+  // Sort and get top questions
+  const mostSkippedQuestions = Object.values(questionSkipCounts)
+    .sort((a, b) => b.count - a.count)
+    .slice(0, 10);
+
+  // Sort and get top categories
+  const mostSkippedCategories = Object.entries(categorySkipCounts)
+    .map(([category, count]) => ({ category, count }))
+    .sort((a, b) => b.count - a.count)
+    .slice(0, 5);
+
+  return {
+    totalSessions: skipHistory.sessions.length,
+    totalSkips: totalManualSkips + totalFilteredSkips,
+    manualSkips: totalManualSkips,
+    filteredSkips: totalFilteredSkips,
+    mostSkippedQuestions,
+    mostSkippedCategories
+  };
+}
+
+module.exports = {
+  SkipTracker,
+  analyzeSkipPatterns
+};

package/lib/learning/storage.js

@@ -0,0 +1,296 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * Learning Storage - Manages learning data persistence
+ *
+ * Handles all file I/O for the learning system with:
+ * - Atomic writes (write to temp, then rename)
+ * - Directory creation
+ * - Data validation
+ * - Error handling
+ */
+
+/**
+ * Get the learning directory path
+ * @param {string} projectPath - Project root path
+ * @returns {string} Learning directory path
+ */
+function getLearningPath(projectPath) {
+  return path.join(projectPath, '.adf', 'learning');
+}
+
+/**
+ * Ensure learning directory exists
+ * @param {string} projectPath - Project root path
+ */
+async function ensureLearningDirectory(projectPath) {
+  const learningPath = getLearningPath(projectPath);
+  await fs.ensureDir(learningPath);
+}
+
+/**
+ * Read learning data file
+ * @param {string} projectPath - Project root path
+ * @param {string} filename - File name (e.g., 'skip-history.json')
+ * @returns {Promise<Object|null>} Data object or null if doesn't exist
+ */
+async function readLearningData(projectPath, filename) {
+  try {
+    const learningPath = getLearningPath(projectPath);
+    const filePath = path.join(learningPath, filename);
+
+    if (!await fs.pathExists(filePath)) {
+      return null;
+    }
+
+    const data = await fs.readJSON(filePath);
+    return data;
+  } catch (error) {
+    console.warn(`Warning: Could not read ${filename}: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Write learning data file atomically
+ * @param {string} projectPath - Project root path
+ * @param {string} filename - File name
+ * @param {Object} data - Data to write
+ */
+async function writeLearningData(projectPath, filename, data) {
+  try {
+    await ensureLearningDirectory(projectPath);
+
+    const learningPath = getLearningPath(projectPath);
+    const filePath = path.join(learningPath, filename);
+    const tempPath = filePath + '.tmp';
+
+    // Write to temp file first (atomic operation)
+    await fs.writeJSON(tempPath, data, { spaces: 2 });
+
+    // Rename temp to actual file (atomic on most filesystems)
+    await fs.rename(tempPath, filePath);
+  } catch (error) {
+    console.error(`Error writing ${filename}: ${error.message}`);
+    throw error;
+  }
+}
+
+/**
+ * Append to learning history file
+ * @param {string} projectPath - Project root path
+ * @param {string} filename - File name
+ * @param {Object} newEntry - New entry to append
+ * @param {string} arrayKey - Key for the array to append to (e.g., 'sessions')
+ */
+async function appendToLearningHistory(projectPath, filename, newEntry, arrayKey = 'sessions') {
+  try {
+    // Read existing data
+    let data = await readLearningData(projectPath, filename);
+
+    if (!data) {
+      // Initialize if doesn't exist
+      data = {
+        version: '1.0',
+        [arrayKey]: []
+      };
+    }
+
+    // Append new entry
+    if (!data[arrayKey]) {
+      data[arrayKey] = [];
+    }
+    data[arrayKey].push(newEntry);
+
+    // Write back
+    await writeLearningData(projectPath, filename, data);
+  } catch (error) {
+    console.error(`Error appending to ${filename}: ${error.message}`);
+    throw error;
+  }
+}
+
+/**
+ * Get skip history
+ * @param {string} projectPath - Project root path
+ * @returns {Promise<Object>} Skip history data
+ */
+async function getSkipHistory(projectPath) {
+  const data = await readLearningData(projectPath, 'skip-history.json');
+  return data || { version: '1.0', sessions: [] };
+}
+
+/**
+ * Get answer history
+ * @param {string} projectPath - Project root path
+ * @returns {Promise<Object>} Answer history data
+ */
+async function getAnswerHistory(projectPath) {
+  const data = await readLearningData(projectPath, 'answer-history.json');
+  return data || { version: '1.0', sessions: [] };
+}
+
+/**
+ * Get detected patterns
+ * @param {string} projectPath - Project root path
+ * @returns {Promise<Object>} Patterns data
+ */
+async function getPatterns(projectPath) {
+  const data = await readLearningData(projectPath, 'patterns.json');
+  return data || { version: '1.0', lastUpdated: null, patterns: [] };
+}
+
+/**
+ * Save patterns
+ * @param {string} projectPath - Project root path
+ * @param {Object} patterns - Patterns data
+ */
+async function savePatterns(projectPath, patterns) {
+  patterns.lastUpdated = new Date().toISOString();
+  await writeLearningData(projectPath, 'patterns.json', patterns);
+}
+
+/**
+ * Get learned rules
+ * @param {string} projectPath - Project root path
+ * @returns {Promise<Object>} Learned rules data
+ */
+async function getLearnedRules(projectPath) {
+  const data = await readLearningData(projectPath, 'learned-rules.json');
+  return data || { version: '1.0', rules: [] };
+}
+
+/**
+ * Save learned rules
+ * @param {string} projectPath - Project root path
+ * @param {Object} rules - Rules data
+ */
+async function saveLearnedRules(projectPath, rules) {
+  await writeLearningData(projectPath, 'learned-rules.json', rules);
+}
+
+/**
+ * Get learning configuration
+ * @param {string} projectPath - Project root path
+ * @returns {Promise<Object>} Config data
+ */
+async function getLearningConfig(projectPath) {
+  const data = await readLearningData(projectPath, 'config.json');
+  return data || {
+    version: '1.0',
+    enabled: true,
+    trackSkips: true,
+    trackAnswers: true,
+    detectPatterns: true,
+    applyLearnedFilters: true,
+    shareAnonymousPatterns: false,
+    minSessionsForPattern: 3,
+    minConfidenceForAutoFilter: 75
+  };
+}
+
+/**
+ * Save learning configuration
+ * @param {string} projectPath - Project root path
+ * @param {Object} config - Config data
+ */
+async function saveLearningConfig(projectPath, config) {
+  await writeLearningData(projectPath, 'config.json', config);
+}
+
+/**
+ * Get learning statistics
+ * @param {string} projectPath - Project root path
+ * @returns {Promise<Object>} Statistics data
+ */
+async function getLearningStats(projectPath) {
+  const data = await readLearningData(projectPath, 'stats.json');
+  return data || {
+    version: '1.0',
+    totalSessions: 0,
+    totalSkips: 0,
+    totalAnswers: 0,
+    patternsDetected: 0,
+    rulesApplied: 0,
+    lastUpdated: null
+  };
+}
+
+/**
+ * Update learning statistics
+ * @param {string} projectPath - Project root path
+ * @param {Object} updates - Statistics updates
+ */
+async function updateLearningStats(projectPath, updates) {
+  const stats = await getLearningStats(projectPath);
+
+  Object.assign(stats, updates);
+  stats.lastUpdated = new Date().toISOString();
+
+  await writeLearningData(projectPath, 'stats.json', stats);
+}
+
+/**
+ * Clear all learning data
+ * @param {string} projectPath - Project root path
+ */
+async function clearLearningData(projectPath) {
+  const learningPath = getLearningPath(projectPath);
+
+  if (await fs.pathExists(learningPath)) {
+    // Remove all JSON files but keep directory
+    const files = await fs.readdir(learningPath);
+    for (const file of files) {
+      if (file.endsWith('.json')) {
+        await fs.remove(path.join(learningPath, file));
+      }
+    }
+  }
+}
+
+/**
+ * Get learning data size in bytes
+ * @param {string} projectPath - Project root path
+ * @returns {Promise<number>} Total size in bytes
+ */
+async function getLearningDataSize(projectPath) {
+  const learningPath = getLearningPath(projectPath);
+
+  if (!await fs.pathExists(learningPath)) {
+    return 0;
+  }
+
+  let totalSize = 0;
+  const files = await fs.readdir(learningPath);
+
+  for (const file of files) {
+    if (file.endsWith('.json')) {
+      const filePath = path.join(learningPath, file);
+      const stats = await fs.stat(filePath);
+      totalSize += stats.size;
+    }
+  }
+
+  return totalSize;
+}
+
+module.exports = {
+  getLearningPath,
+  ensureLearningDirectory,
+  readLearningData,
+  writeLearningData,
+  appendToLearningHistory,
+  getSkipHistory,
+  getAnswerHistory,
+  getPatterns,
+  savePatterns,
+  getLearnedRules,
+  saveLearnedRules,
+  getLearningConfig,
+  saveLearningConfig,
+  getLearningStats,
+  updateLearningStats,
+  clearLearningData,
+  getLearningDataSize
+};

package/package.json

@@ -1,69 +1,70 @@
-{
-  "name": "@iservu-inc/adf-cli",
-  "version": "0.3.6",
-  "description": "CLI tool for AgentDevFramework - AI-assisted development framework with multi-provider AI support",
-  "main": "index.js",
-  "bin": {
-    "adf": "bin/adf.js"
-  },
-  "scripts": {
-    "test": "jest --coverage",
-    "test:watch": "jest --watch"
-  },
-  "keywords": [
-    "cli",
-    "framework",
-    "ai",
-    "development",
-    "agent",
-    "bmad",
-    "spec-kit",
-    "context-engineering",
-    "prp",
-    "agentic",
-    "tdd",
-    "windsurf",
-    "cursor",
-    "claude-code",
-    "anthropic",
-    "openai",
-    "gemini",
-    "openrouter",
-    "llm",
-    "requirements-gathering"
-  ],
-  "author": "iServU",
-  "license": "MIT",
-  "dependencies": {
-    "@anthropic-ai/sdk": "^0.32.0",
-    "@google/generative-ai": "^0.21.0",
-    "chalk": "^4.1.2",
-    "commander": "^11.1.0",
-    "dotenv": "^17.2.3",
-    "fs-extra": "^11.2.0",
-    "inquirer": "^8.2.5",
-    "inquirer-autocomplete-prompt": "^2.0.1",
-    "node-fetch": "^2.7.0",
-    "openai": "^4.73.0",
-    "ora": "^5.4.1"
-  },
-  "engines": {
-    "node": ">=18.0.0",
-    "npm": ">=9.0.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/iservu/adf-cli.git"
-  },
-  "bugs": {
-    "url": "https://github.com/iservu/adf-cli/issues"
-  },
-  "homepage": "https://github.com/iservu/adf-cli#readme",
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "@types/node": "^24.6.2",
-    "jest": "^30.2.0"
-  }
-}
+{
+  "name": "@iservu-inc/adf-cli",
+  "version": "0.4.12",
+  "description": "CLI tool for AgentDevFramework - AI-assisted development framework with multi-provider AI support",
+  "main": "index.js",
+  "bin": {
+    "adf": "bin/adf.js"
+  },
+  "scripts": {
+    "test": "jest --coverage",
+    "test:watch": "jest --watch"
+  },
+  "keywords": [
+    "cli",
+    "framework",
+    "ai",
+    "development",
+    "agent",
+    "bmad",
+    "spec-kit",
+    "context-engineering",
+    "prp",
+    "agentic",
+    "tdd",
+    "windsurf",
+    "cursor",
+    "claude-code",
+    "anthropic",
+    "openai",
+    "gemini",
+    "openrouter",
+    "llm",
+    "requirements-gathering"
+  ],
+  "author": "iServU",
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.32.0",
+    "@google/generative-ai": "^0.21.0",
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "dotenv": "^17.2.3",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^8.2.5",
+    "inquirer-autocomplete-prompt": "^2.0.1",
+    "node-fetch": "^2.7.0",
+    "openai": "^4.73.0",
+    "ora": "^5.4.1",
+    "uuid": "^9.0.1"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "npm": ">=9.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iservu/adf-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/iservu/adf-cli/issues"
+  },
+  "homepage": "https://github.com/iservu/adf-cli#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.2",
+    "jest": "^30.2.0"
+  }
+}