@butlerw/vellum 0.1.0

package/src/onboarding/tutorial/progress-tracker.ts

@@ -0,0 +1,350 @@
+/**
+ * Progress Tracker
+ *
+ * Tracks and manages tutorial progress across lessons and steps.
+ *
+ * @module cli/onboarding/tutorial/progress-tracker
+ */
+
+import {
+  INITIAL_LESSON_PROGRESS,
+  type Lesson,
+  type LessonProgress,
+  type TutorialProgress,
+  type TutorialStorage,
+} from "./types.js";
+
+// =============================================================================
+// Progress Statistics
+// =============================================================================
+
+/**
+ * Detailed progress statistics
+ */
+export interface ProgressStats {
+  /** Total lessons in tutorial */
+  totalLessons: number;
+  /** Completed lessons count */
+  completedLessons: number;
+  /** Started but incomplete lessons */
+  inProgressLessons: number;
+  /** Not started lessons */
+  notStartedLessons: number;
+  /** Total steps across all lessons */
+  totalSteps: number;
+  /** Completed steps count */
+  completedSteps: number;
+  /** Completion percentage (0-100) */
+  completionPercent: number;
+  /** Total time spent in minutes */
+  totalTimeMinutes: number;
+  /** Estimated remaining time in minutes */
+  estimatedRemainingMinutes: number;
+}
+
+// =============================================================================
+// Progress Tracker Class
+// =============================================================================
+
+/**
+ * Tracks and manages tutorial progress
+ */
+export class ProgressTracker {
+  private storage: TutorialStorage;
+  private lessons: readonly Lesson[];
+  private cachedProgress: TutorialProgress | null = null;
+
+  constructor(storage: TutorialStorage, lessons: readonly Lesson[]) {
+    this.storage = storage;
+    this.lessons = lessons;
+  }
+
+  // ===========================================================================
+  // Progress Loading
+  // ===========================================================================
+
+  /**
+   * Load progress from storage
+   */
+  async loadProgress(): Promise<TutorialProgress> {
+    this.cachedProgress = await this.storage.loadProgress();
+    return this.cachedProgress;
+  }
+
+  /**
+   * Get cached progress or load if not cached
+   */
+  async getProgress(): Promise<TutorialProgress> {
+    if (!this.cachedProgress) {
+      return this.loadProgress();
+    }
+    return this.cachedProgress;
+  }
+
+  // ===========================================================================
+  // Lesson Progress
+  // ===========================================================================
+
+  /**
+   * Start a lesson
+   */
+  async startLesson(lessonId: string): Promise<LessonProgress> {
+    const progress = await this.getProgress();
+    const existing = progress.lessons[lessonId];
+
+    // Already started
+    if (existing?.started) {
+      return existing;
+    }
+
+    const now = new Date().toISOString();
+    const lessonProgress: LessonProgress = {
+      ...INITIAL_LESSON_PROGRESS,
+      lessonId,
+      started: true,
+      startedAt: now,
+      currentStepIndex: 0,
+      completedSteps: [],
+      totalTimeSpent: 0,
+    };
+
+    await this.storage.updateLessonProgress(lessonId, lessonProgress);
+
+    // Update cache
+    progress.lessons[lessonId] = lessonProgress;
+    progress.lastActiveLessonId = lessonId;
+    progress.lastActivityAt = now;
+
+    if (!progress.startedAt) {
+      progress.startedAt = now;
+      await this.storage.saveProgress(progress);
+    }
+
+    this.cachedProgress = progress;
+    return lessonProgress;
+  }
+
+  /**
+   * Complete a step in a lesson
+   */
+  async completeStep(lessonId: string, stepId: string, timeSpent?: number): Promise<void> {
+    const progress = await this.getProgress();
+    const lessonProgress = progress.lessons[lessonId];
+
+    if (!lessonProgress) {
+      throw new Error(`Lesson ${lessonId} not started`);
+    }
+
+    // Already completed
+    if (lessonProgress.completedSteps.includes(stepId)) {
+      return;
+    }
+
+    // Update lesson progress
+    const updatedSteps = [...lessonProgress.completedSteps, stepId];
+    const updatedTime = lessonProgress.totalTimeSpent + (timeSpent ?? 0);
+
+    await this.storage.updateLessonProgress(lessonId, {
+      completedSteps: updatedSteps,
+      currentStepIndex: updatedSteps.length,
+      totalTimeSpent: updatedTime,
+    });
+
+    // Update cache
+    lessonProgress.completedSteps = updatedSteps;
+    lessonProgress.currentStepIndex = updatedSteps.length;
+    lessonProgress.totalTimeSpent = updatedTime;
+    progress.stepsCompleted++;
+    progress.lastActivityAt = new Date().toISOString();
+
+    this.cachedProgress = progress;
+  }
+
+  /**
+   * Complete a lesson
+   */
+  async completeLesson(lessonId: string): Promise<void> {
+    const progress = await this.getProgress();
+    const lessonProgress = progress.lessons[lessonId];
+
+    if (!lessonProgress) {
+      throw new Error(`Lesson ${lessonId} not started`);
+    }
+
+    // Already completed
+    if (lessonProgress.completed) {
+      return;
+    }
+
+    const now = new Date().toISOString();
+
+    await this.storage.updateLessonProgress(lessonId, {
+      completed: true,
+      completedAt: now,
+    });
+
+    // Update cache
+    lessonProgress.completed = true;
+    lessonProgress.completedAt = now;
+    progress.lessonsCompleted++;
+    progress.lastActivityAt = now;
+
+    await this.storage.saveProgress(progress);
+    this.cachedProgress = progress;
+  }
+
+  /**
+   * Get progress for a specific lesson
+   */
+  async getLessonProgress(lessonId: string): Promise<LessonProgress | undefined> {
+    const progress = await this.getProgress();
+    return progress.lessons[lessonId];
+  }
+
+  /**
+   * Check if lesson is completed
+   */
+  async isLessonCompleted(lessonId: string): Promise<boolean> {
+    const lessonProgress = await this.getLessonProgress(lessonId);
+    return lessonProgress?.completed ?? false;
+  }
+
+  /**
+   * Get current step in a lesson
+   */
+  async getCurrentStep(lessonId: string): Promise<number> {
+    const lessonProgress = await this.getLessonProgress(lessonId);
+    return lessonProgress?.currentStepIndex ?? 0;
+  }
+
+  // ===========================================================================
+  // Statistics
+  // ===========================================================================
+
+  /**
+   * Get detailed progress statistics
+   */
+  async getStats(): Promise<ProgressStats> {
+    const progress = await this.getProgress();
+
+    let completedLessons = 0;
+    let inProgressLessons = 0;
+    let notStartedLessons = 0;
+    let totalSteps = 0;
+    let completedSteps = 0;
+    let totalTimeSeconds = 0;
+    let estimatedRemainingSeconds = 0;
+
+    for (const lesson of this.lessons) {
+      const lessonProgress = progress.lessons[lesson.id];
+      totalSteps += lesson.steps.length;
+
+      if (lessonProgress?.completed) {
+        completedLessons++;
+        completedSteps += lesson.steps.length;
+        totalTimeSeconds += lessonProgress.totalTimeSpent;
+      } else if (lessonProgress?.started) {
+        inProgressLessons++;
+        completedSteps += lessonProgress.completedSteps.length;
+        totalTimeSeconds += lessonProgress.totalTimeSpent;
+
+        // Estimate remaining for in-progress lesson
+        const remainingSteps = lesson.steps.length - lessonProgress.completedSteps.length;
+        const avgStepTime = (lesson.estimatedMinutes * 60) / lesson.steps.length;
+        estimatedRemainingSeconds += remainingSteps * avgStepTime;
+      } else {
+        notStartedLessons++;
+        estimatedRemainingSeconds += lesson.estimatedMinutes * 60;
+      }
+    }
+
+    const totalLessons = this.lessons.length;
+    const completionPercent = totalSteps > 0 ? Math.round((completedSteps / totalSteps) * 100) : 0;
+
+    return {
+      totalLessons,
+      completedLessons,
+      inProgressLessons,
+      notStartedLessons,
+      totalSteps,
+      completedSteps,
+      completionPercent,
+      totalTimeMinutes: Math.round(totalTimeSeconds / 60),
+      estimatedRemainingMinutes: Math.round(estimatedRemainingSeconds / 60),
+    };
+  }
+
+  /**
+   * Get completion percentage for a lesson
+   */
+  async getLessonCompletionPercent(lessonId: string): Promise<number> {
+    const lesson = this.lessons.find((l) => l.id === lessonId);
+    if (!lesson) return 0;
+
+    const lessonProgress = await this.getLessonProgress(lessonId);
+    if (!lessonProgress) return 0;
+
+    const totalSteps = lesson.steps.length;
+    const completedSteps = lessonProgress.completedSteps.length;
+
+    return totalSteps > 0 ? Math.round((completedSteps / totalSteps) * 100) : 0;
+  }
+
+  /**
+   * Check if all tutorials are complete
+   */
+  async isAllComplete(): Promise<boolean> {
+    const progress = await this.getProgress();
+    return this.lessons.every((lesson) => progress.lessons[lesson.id]?.completed);
+  }
+
+  /**
+   * Get completed lesson IDs
+   */
+  async getCompletedLessonIds(): Promise<string[]> {
+    const progress = await this.getProgress();
+    return Object.entries(progress.lessons)
+      .filter(([_, p]) => (p as { completed: boolean }).completed)
+      .map(([id]) => id);
+  }
+
+  // ===========================================================================
+  // Reset
+  // ===========================================================================
+
+  /**
+   * Reset all progress
+   */
+  async resetAll(): Promise<void> {
+    await this.storage.resetProgress();
+    this.cachedProgress = null;
+  }
+
+  /**
+   * Reset a single lesson
+   */
+  async resetLesson(lessonId: string): Promise<void> {
+    await this.storage.updateLessonProgress(lessonId, {
+      ...INITIAL_LESSON_PROGRESS,
+      lessonId,
+    });
+
+    if (this.cachedProgress) {
+      delete this.cachedProgress.lessons[lessonId];
+    }
+  }
+}
+
+// =============================================================================
+// Factory
+// =============================================================================
+
+/**
+ * Create a progress tracker
+ */
+export function createProgressTracker(
+  storage: TutorialStorage,
+  lessons: readonly Lesson[]
+): ProgressTracker {
+  return new ProgressTracker(storage, lessons);
+}

package/src/onboarding/tutorial/storage.ts

@@ -0,0 +1,249 @@
+/**
+ * Tutorial Storage
+ *
+ * Handles persistence of tutorial progress to disk.
+ *
+ * @module cli/onboarding/tutorial/storage
+ */
+
+import * as fs from "node:fs";
+import * as fsPromises from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import {
+  INITIAL_LESSON_PROGRESS,
+  INITIAL_TUTORIAL_PROGRESS,
+  type LessonProgress,
+  type TutorialProgress,
+  TutorialProgressSchema,
+  type TutorialStorage,
+} from "./types.js";
+
+// =============================================================================
+// Paths
+// =============================================================================
+
+/**
+ * Get Vellum config directory
+ */
+function getVellumDir(): string {
+  const home = os.homedir();
+  return path.join(home, ".vellum");
+}
+
+/**
+ * Get tutorial progress file path
+ */
+function getTutorialProgressPath(): string {
+  return path.join(getVellumDir(), "tutorial-progress.json");
+}
+
+// =============================================================================
+// File Storage Implementation
+// =============================================================================
+
+/**
+ * File-based tutorial storage
+ */
+export class FileTutorialStorage implements TutorialStorage {
+  private progressPath: string;
+  private cachedProgress: TutorialProgress | null = null;
+
+  constructor(customPath?: string) {
+    this.progressPath = customPath ?? getTutorialProgressPath();
+  }
+
+  /**
+   * Ensure the storage directory exists
+   */
+  private async ensureDir(): Promise<void> {
+    const dir = path.dirname(this.progressPath);
+    if (!fs.existsSync(dir)) {
+      await fsPromises.mkdir(dir, { recursive: true });
+    }
+  }
+
+  /**
+   * Load tutorial progress from file
+   */
+  async loadProgress(): Promise<TutorialProgress> {
+    // Return cached if available
+    if (this.cachedProgress) {
+      return this.cachedProgress;
+    }
+
+    try {
+      if (!fs.existsSync(this.progressPath)) {
+        return { ...INITIAL_TUTORIAL_PROGRESS };
+      }
+
+      const content = await fsPromises.readFile(this.progressPath, "utf-8");
+      const data = JSON.parse(content) as unknown;
+      const parsed = TutorialProgressSchema.safeParse(data);
+
+      if (parsed.success) {
+        this.cachedProgress = parsed.data;
+        return parsed.data;
+      }
+
+      // Invalid data, return initial state
+      console.warn("[TutorialStorage] Invalid progress data, resetting");
+      return { ...INITIAL_TUTORIAL_PROGRESS };
+    } catch (error) {
+      // File doesn't exist or parse error
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+        console.warn("[TutorialStorage] Failed to load progress:", error);
+      }
+      return { ...INITIAL_TUTORIAL_PROGRESS };
+    }
+  }
+
+  /**
+   * Save tutorial progress to file
+   */
+  async saveProgress(progress: TutorialProgress): Promise<void> {
+    try {
+      await this.ensureDir();
+
+      // Validate before saving
+      const parsed = TutorialProgressSchema.safeParse(progress);
+      if (!parsed.success) {
+        throw new Error(`Invalid progress data: ${parsed.error.message}`);
+      }
+
+      // Update cache
+      this.cachedProgress = parsed.data;
+
+      // Write to file
+      const content = JSON.stringify(parsed.data, null, 2);
+      await fsPromises.writeFile(this.progressPath, content, "utf-8");
+    } catch (error) {
+      console.error("[TutorialStorage] Failed to save progress:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Reset all progress
+   */
+  async resetProgress(): Promise<void> {
+    try {
+      this.cachedProgress = null;
+
+      if (fs.existsSync(this.progressPath)) {
+        await fsPromises.unlink(this.progressPath);
+      }
+    } catch (error) {
+      console.error("[TutorialStorage] Failed to reset progress:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get progress for a specific lesson
+   */
+  async getLessonProgress(lessonId: string): Promise<LessonProgress | undefined> {
+    const progress = await this.loadProgress();
+    return progress.lessons[lessonId];
+  }
+
+  /**
+   * Update progress for a specific lesson
+   */
+  async updateLessonProgress(lessonId: string, updates: Partial<LessonProgress>): Promise<void> {
+    const progress = await this.loadProgress();
+
+    // Get or create lesson progress
+    const existing = progress.lessons[lessonId] ?? {
+      ...INITIAL_LESSON_PROGRESS,
+      lessonId,
+    };
+
+    // Merge updates
+    progress.lessons[lessonId] = {
+      ...existing,
+      ...updates,
+    };
+
+    // Update last activity
+    progress.lastActivityAt = new Date().toISOString();
+    progress.lastActiveLessonId = lessonId;
+
+    await this.saveProgress(progress);
+  }
+
+  /**
+   * Clear the cache (useful for testing)
+   */
+  clearCache(): void {
+    this.cachedProgress = null;
+  }
+}
+
+// =============================================================================
+// In-Memory Storage (for testing)
+// =============================================================================
+
+/**
+ * In-memory tutorial storage for testing
+ */
+export class MemoryTutorialStorage implements TutorialStorage {
+  private progress: TutorialProgress = { ...INITIAL_TUTORIAL_PROGRESS };
+
+  async loadProgress(): Promise<TutorialProgress> {
+    return { ...this.progress };
+  }
+
+  async saveProgress(progress: TutorialProgress): Promise<void> {
+    this.progress = { ...progress };
+  }
+
+  async resetProgress(): Promise<void> {
+    this.progress = { ...INITIAL_TUTORIAL_PROGRESS };
+  }
+
+  async getLessonProgress(lessonId: string): Promise<LessonProgress | undefined> {
+    return this.progress.lessons[lessonId];
+  }
+
+  async updateLessonProgress(lessonId: string, updates: Partial<LessonProgress>): Promise<void> {
+    const existing = this.progress.lessons[lessonId] ?? {
+      ...INITIAL_LESSON_PROGRESS,
+      lessonId,
+    };
+
+    this.progress.lessons[lessonId] = {
+      ...existing,
+      ...updates,
+    };
+
+    this.progress.lastActivityAt = new Date().toISOString();
+    this.progress.lastActiveLessonId = lessonId;
+  }
+
+  /**
+   * Get raw progress (for testing)
+   */
+  getRawProgress(): TutorialProgress {
+    return this.progress;
+  }
+
+  /**
+   * Set raw progress (for testing)
+   */
+  setRawProgress(progress: TutorialProgress): void {
+    this.progress = progress;
+  }
+}
+
+// =============================================================================
+// Factory
+// =============================================================================
+
+/**
+ * Create a tutorial storage instance
+ */
+export function createTutorialStorage(customPath?: string): TutorialStorage {
+  return new FileTutorialStorage(customPath);
+}