@cloudstreamsoftware/claude-tools 1.0.0 → 1.1.0

package/scripts/lib/tutorial-metrics.js

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+/**
+ * Tutorial metrics collection module.
+ * Tracks local, privacy-respecting analytics for tutorial usage.
+ *
+ * Metrics are stored in ~/.claude/tutorial-metrics.json
+ * No external telemetry - data stays on your machine.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Metrics file location
+const METRICS_DIR = path.join(os.homedir(), '.claude');
+const METRICS_FILE = path.join(METRICS_DIR, 'tutorial-metrics.json');
+
+/**
+ * Ensure the metrics directory exists.
+ */
+function ensureMetricsDir() {
+  if (!fs.existsSync(METRICS_DIR)) {
+    fs.mkdirSync(METRICS_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Get default metrics state.
+ * @returns {object} Default metrics object
+ */
+function getDefaultMetrics() {
+  return {
+    lessonMetrics: {},
+    overallMetrics: {
+      startedAt: new Date().toISOString(),
+      completedAt: null,
+      totalSessions: 0,
+      totalTimeMs: 0,
+    },
+    activeLesson: null,
+    activeLessonStartTime: null,
+  };
+}
+
+/**
+ * Load metrics from file.
+ * @returns {object} Metrics state or default if not exists
+ */
+function loadMetrics() {
+  try {
+    if (fs.existsSync(METRICS_FILE)) {
+      const data = fs.readFileSync(METRICS_FILE, 'utf8');
+      return JSON.parse(data);
+    }
+  } catch {
+    // If file is corrupted, start fresh
+  }
+  return getDefaultMetrics();
+}
+
+/**
+ * Save metrics to file.
+ * @param {object} metrics - Metrics state to save
+ */
+function saveMetrics(metrics) {
+  ensureMetricsDir();
+  fs.writeFileSync(METRICS_FILE, JSON.stringify(metrics, null, 2));
+}
+
+/**
+ * Record that a lesson was started/viewed.
+ * @param {number} lessonNum - Lesson number (1-9)
+ * @returns {object} Updated metrics
+ */
+function recordLessonStart(lessonNum) {
+  const metrics = loadMetrics();
+
+  // Initialize lesson metrics if needed
+  if (!metrics.lessonMetrics[lessonNum]) {
+    metrics.lessonMetrics[lessonNum] = {
+      visits: 0,
+      totalTimeMs: 0,
+      lastVisit: null,
+    };
+  }
+
+  // Increment visit count
+  metrics.lessonMetrics[lessonNum].visits++;
+  metrics.lessonMetrics[lessonNum].lastVisit = new Date().toISOString();
+
+  // Track active lesson for time calculation
+  metrics.activeLesson = lessonNum;
+  metrics.activeLessonStartTime = Date.now();
+
+  saveMetrics(metrics);
+  return metrics;
+}
+
+/**
+ * Record that a lesson was completed/ended.
+ * @param {number} lessonNum - Lesson number (1-9)
+ * @returns {object} Updated metrics
+ */
+function recordLessonEnd(lessonNum) {
+  const metrics = loadMetrics();
+
+  // Calculate time spent if this was the active lesson
+  if (metrics.activeLesson === lessonNum && metrics.activeLessonStartTime) {
+    const timeSpent = Date.now() - metrics.activeLessonStartTime;
+
+    if (!metrics.lessonMetrics[lessonNum]) {
+      metrics.lessonMetrics[lessonNum] = {
+        visits: 1,
+        totalTimeMs: 0,
+        lastVisit: new Date().toISOString(),
+      };
+    }
+
+    metrics.lessonMetrics[lessonNum].totalTimeMs += timeSpent;
+    metrics.overallMetrics.totalTimeMs += timeSpent;
+  }
+
+  // Clear active lesson
+  metrics.activeLesson = null;
+  metrics.activeLessonStartTime = null;
+
+  saveMetrics(metrics);
+  return metrics;
+}
+
+/**
+ * Record a new session.
+ * @returns {object} Updated metrics
+ */
+function recordSession() {
+  const metrics = loadMetrics();
+  metrics.overallMetrics.totalSessions++;
+  saveMetrics(metrics);
+  return metrics;
+}
+
+/**
+ * Mark tutorial as completed.
+ * @returns {object} Updated metrics
+ */
+function markComplete() {
+  const metrics = loadMetrics();
+  metrics.overallMetrics.completedAt = new Date().toISOString();
+  saveMetrics(metrics);
+  return metrics;
+}
+
+/**
+ * Format milliseconds as human-readable time.
+ * @param {number} ms - Milliseconds
+ * @returns {string} Formatted time string
+ */
+function formatTime(ms) {
+  if (ms < 1000) return '< 1s';
+
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+
+  if (hours > 0) {
+    const remainingMinutes = minutes % 60;
+    return `${hours}h ${remainingMinutes}m`;
+  }
+  if (minutes > 0) {
+    const remainingSeconds = seconds % 60;
+    return `${minutes}m ${remainingSeconds}s`;
+  }
+  return `${seconds}s`;
+}
+
+/**
+ * Get summary statistics.
+ * @returns {object} Stats object
+ */
+function getStats() {
+  const metrics = loadMetrics();
+
+  // Calculate most visited lesson
+  let mostVisited = null;
+  let maxVisits = 0;
+
+  for (const [lessonNum, data] of Object.entries(metrics.lessonMetrics)) {
+    if (data.visits > maxVisits) {
+      maxVisits = data.visits;
+      mostVisited = parseInt(lessonNum, 10);
+    }
+  }
+
+  // Calculate average time per lesson
+  const lessonCount = Object.keys(metrics.lessonMetrics).length;
+  const avgTimeMs = lessonCount > 0 ? metrics.overallMetrics.totalTimeMs / lessonCount : 0;
+
+  return {
+    totalTime: formatTime(metrics.overallMetrics.totalTimeMs),
+    totalTimeMs: metrics.overallMetrics.totalTimeMs,
+    totalSessions: metrics.overallMetrics.totalSessions,
+    lessonsVisited: lessonCount,
+    mostVisited: mostVisited,
+    mostVisitedCount: maxVisits,
+    averageTimePerLesson: formatTime(avgTimeMs),
+    startedAt: metrics.overallMetrics.startedAt,
+    completedAt: metrics.overallMetrics.completedAt,
+    lessonMetrics: metrics.lessonMetrics,
+  };
+}
+
+/**
+ * Reset all metrics.
+ * @returns {object} Fresh metrics state
+ */
+function resetMetrics() {
+  const metrics = getDefaultMetrics();
+  saveMetrics(metrics);
+  return metrics;
+}
+
+/**
+ * Check if metrics file exists.
+ * @returns {boolean} True if metrics file exists
+ */
+function hasMetrics() {
+  return fs.existsSync(METRICS_FILE);
+}
+
+module.exports = {
+  METRICS_FILE,
+  loadMetrics,
+  saveMetrics,
+  recordLessonStart,
+  recordLessonEnd,
+  recordSession,
+  markComplete,
+  getStats,
+  resetMetrics,
+  hasMetrics,
+  formatTime,
+};

package/scripts/lib/tutorial-progress.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+/**
+ * Tutorial progress persistence module.
+ * Manages progress state for the interactive tutorial system.
+ *
+ * Progress is stored in ~/.claude/tutorial-progress.json
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Progress file location
+const PROGRESS_DIR = path.join(os.homedir(), '.claude');
+const PROGRESS_FILE = path.join(PROGRESS_DIR, 'tutorial-progress.json');
+
+// Total lessons in the tutorial (lessons 0-14 = 15 lessons total)
+const TOTAL_LESSONS = 15;
+
+// Lesson metadata (lesson numbers 1-14 for display, but lesson 0 is Philosophy)
+const LESSONS = [
+  { num: 0, file: '00-philosophy-and-workflow.md', title: 'Philosophy & Workflow' },
+  { num: 1, file: '01-basics.md', title: 'Core Concepts' },
+  { num: 2, file: '02-training.md', title: 'Training Mode' },
+  { num: 3, file: '03-commands.md', title: 'Essential Commands' },
+  { num: 4, file: '04-workflows.md', title: 'Workflow Patterns' },
+  { num: 5, file: '05-compliance.md', title: 'Compliance' },
+  { num: 6, file: '06-zoho.md', title: 'Zoho Development' },
+  { num: 7, file: '07-hooks-system.md', title: 'Hooks System' },
+  { num: 8, file: '08-mcp-servers.md', title: 'MCP Servers' },
+  { num: 9, file: '09-client-management.md', title: 'Client Management' },
+  { num: 10, file: '10-testing-e2e.md', title: 'Testing & E2E' },
+  { num: 11, file: '11-skills-deep-dive.md', title: 'Skills Deep Dive' },
+  { num: 12, file: '12-rules-system.md', title: 'Rules System' },
+  { num: 13, file: '13-golden-standard-graduation.md', title: 'Golden Standard Graduation' },
+  { num: 14, file: '14-fork-setup-and-sync.md', title: 'Fork Setup & Sync' },
+];
+
+/**
+ * Ensure the progress directory exists.
+ */
+function ensureProgressDir() {
+  if (!fs.existsSync(PROGRESS_DIR)) {
+    fs.mkdirSync(PROGRESS_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Get default progress state.
+ * @returns {object} Default progress object
+ */
+function getDefaultProgress() {
+  return {
+    currentLesson: 0, // Start with lesson 0 (Philosophy)
+    completedLessons: [],
+    startedAt: new Date().toISOString(),
+    lastAccessed: new Date().toISOString(),
+    totalSessions: 1,
+  };
+}
+
+/**
+ * Load progress from file.
+ * @returns {object} Progress state or default if not exists
+ */
+function loadProgress() {
+  try {
+    if (fs.existsSync(PROGRESS_FILE)) {
+      const data = fs.readFileSync(PROGRESS_FILE, 'utf8');
+      const progress = JSON.parse(data);
+      // Update last accessed time
+      progress.lastAccessed = new Date().toISOString();
+      progress.totalSessions = (progress.totalSessions || 0) + 1;
+      return progress;
+    }
+  } catch {
+    // If file is corrupted, start fresh
+  }
+  return getDefaultProgress();
+}
+
+/**
+ * Save progress to file.
+ * @param {object} progress - Progress state to save
+ */
+function saveProgress(progress) {
+  ensureProgressDir();
+  progress.lastAccessed = new Date().toISOString();
+  fs.writeFileSync(PROGRESS_FILE, JSON.stringify(progress, null, 2));
+}
+
+/**
+ * Mark a lesson as completed.
+ * @param {number} lessonNum - Lesson number (0-14)
+ * @returns {object} Updated progress
+ */
+function completeLesson(lessonNum) {
+  const progress = loadProgress();
+
+  if (!progress.completedLessons.includes(lessonNum)) {
+    progress.completedLessons.push(lessonNum);
+    progress.completedLessons.sort((a, b) => a - b);
+  }
+
+  // Move to next lesson if current (max lesson is TOTAL_LESSONS - 1)
+  if (lessonNum === progress.currentLesson && lessonNum < TOTAL_LESSONS - 1) {
+    progress.currentLesson = lessonNum + 1;
+  }
+
+  // Check for completion
+  if (progress.completedLessons.length === TOTAL_LESSONS) {
+    progress.completedAt = new Date().toISOString();
+  }
+
+  saveProgress(progress);
+  return progress;
+}
+
+/**
+ * Set the current lesson.
+ * @param {number} lessonNum - Lesson number (0-14)
+ * @returns {object} Updated progress
+ */
+function setCurrentLesson(lessonNum) {
+  if (lessonNum < 0 || lessonNum >= TOTAL_LESSONS) {
+    throw new Error(`Invalid lesson number: ${lessonNum}. Must be 0-${TOTAL_LESSONS - 1}`);
+  }
+  const progress = loadProgress();
+  progress.currentLesson = lessonNum;
+  saveProgress(progress);
+  return progress;
+}
+
+/**
+ * Reset all progress.
+ * @returns {object} Fresh progress state
+ */
+function resetProgress() {
+  const progress = getDefaultProgress();
+  saveProgress(progress);
+  return progress;
+}
+
+/**
+ * Get completion percentage.
+ * @param {object} progress - Progress state
+ * @returns {number} Completion percentage (0-100)
+ */
+function getCompletionPercent(progress) {
+  return Math.round((progress.completedLessons.length / TOTAL_LESSONS) * 100);
+}
+
+/**
+ * Check if tutorial is complete.
+ * @param {object} progress - Progress state
+ * @returns {boolean} True if all lessons completed
+ */
+function isComplete(progress) {
+  return progress.completedLessons.length === TOTAL_LESSONS;
+}
+
+/**
+ * Get lesson info by number.
+ * @param {number} lessonNum - Lesson number (0-14)
+ * @returns {object|null} Lesson info or null
+ */
+function getLessonInfo(lessonNum) {
+  return LESSONS.find((l) => l.num === lessonNum) || null;
+}
+
+/**
+ * Get lesson status for display.
+ * @param {object} progress - Progress state
+ * @param {number} lessonNum - Lesson number
+ * @returns {string} Status: 'completed', 'current', or 'pending'
+ */
+function getLessonStatus(progress, lessonNum) {
+  if (progress.completedLessons.includes(lessonNum)) {
+    return 'completed';
+  }
+  if (lessonNum === progress.currentLesson) {
+    return 'current';
+  }
+  return 'pending';
+}
+
+/**
+ * Check if progress file exists.
+ * @returns {boolean} True if progress file exists
+ */
+function hasProgress() {
+  return fs.existsSync(PROGRESS_FILE);
+}
+
+module.exports = {
+  TOTAL_LESSONS,
+  LESSONS,
+  PROGRESS_FILE,
+  loadProgress,
+  saveProgress,
+  completeLesson,
+  setCurrentLesson,
+  resetProgress,
+  getCompletionPercent,
+  isComplete,
+  getLessonInfo,
+  getLessonStatus,
+  hasProgress,
+};