@learnpack/learnpack 5.0.329 → 5.0.331

package/src/managers/historyManager.ts

@@ -0,0 +1,281 @@
+import type { RedisClientType } from "redis"
+import * as fs from "fs"
+import * as path from "path"
+
+interface StateData {
+  content: string;
+  timestamp: number;
+}
+
+export interface HistoryResult {
+  success: boolean;
+  newVersion?: string;
+  content?: string;
+  error?: string;
+}
+
+export interface HistoryStatus {
+  canUndo: boolean;
+  canRedo: boolean;
+  version: string;
+}
+
+export class HistoryManager {
+  private redis: RedisClientType
+  private saveStateLua: string
+  private undoLua: string
+  private redoLua: string
+
+  private readonly TTL = "432000" // 5 days in seconds
+  private readonly LIMIT = 5 // Keep last 5 states
+
+  constructor(redisClient: RedisClientType) {
+    this.redis = redisClient
+
+    // Load Lua scripts
+    const luaDir = path.join(__dirname, "../lua")
+    this.saveStateLua = fs.readFileSync(
+      path.join(luaDir, "saveState.lua"),
+      "utf8"
+    )
+    this.undoLua = fs.readFileSync(path.join(luaDir, "undo.lua"), "utf8")
+    this.redoLua = fs.readFileSync(path.join(luaDir, "redo.lua"), "utf8")
+  }
+
+  /**
+   * Builds Redis keys for an exercise in a specific language
+   * @param courseSlug - The course slug identifier
+   * @param exerciseSlug - The exercise slug identifier
+   * @param lang - The language code
+   * @returns Object containing undo, redo, and version keys
+   */
+  private getKeys(courseSlug: string, exerciseSlug: string, lang: string) {
+    const baseKey = `${courseSlug}:${exerciseSlug}:${lang}`
+    return {
+      undo: `undo:${baseKey}`,
+      redo: `redo:${baseKey}`,
+      version: `undo:${baseKey}:version`,
+    }
+  }
+
+  /**
+   * Saves a new state in history
+   * @param courseSlug - The course slug identifier
+   * @param exerciseSlug - The exercise slug identifier
+   * @param lang - The language code
+   * @param content - The content of the state
+   * @param versionId - The version ID
+   * @returns Object containing success, newVersion, and error
+   */
+  async saveState(
+    courseSlug: string,
+    exerciseSlug: string,
+    lang: string,
+    content: string,
+    versionId: string
+  ): Promise<HistoryResult> {
+    const keys = this.getKeys(courseSlug, exerciseSlug, lang)
+
+    const state: StateData = {
+      content,
+      timestamp: Date.now(),
+    }
+
+    const stateJson = JSON.stringify(state)
+
+    try {
+      // Official Redis client syntax: eval(script, { keys: [...], arguments: [...] })
+      const result: any = await this.redis.eval(this.saveStateLua, {
+        keys: [keys.undo, keys.redo, keys.version],
+        arguments: [
+          stateJson,
+          versionId,
+          this.TTL.toString(),
+          this.LIMIT.toString(),
+        ],
+      })
+
+      // Check if it's an error response (table with err field)
+      if (result && typeof result === "object" && result.err) {
+        return { success: false, error: result.err }
+      }
+
+      // Success response is a string (the new version)
+      const newVersion = typeof result === "string" ? result : String(result)
+      return { success: true, newVersion }
+    } catch (error: any) {
+      console.error("⏮️  HISTORY: Error saving state to Redis:", error)
+      return { success: false, error: error.message }
+    }
+  }
+
+  /**
+   * Performs an undo operation
+   * @param courseSlug - The course slug identifier
+   * @param exerciseSlug - The exercise slug identifier
+   * @param lang - The language code
+   * @param currentContent - The current content of the state
+   * @param versionId - The version ID
+   * @returns Object containing success, newVersion, and error
+   */
+  async undo(
+    courseSlug: string,
+    exerciseSlug: string,
+    lang: string,
+    currentContent: string,
+    versionId: string
+  ): Promise<HistoryResult> {
+    const keys = this.getKeys(courseSlug, exerciseSlug, lang)
+
+    const currentState: StateData = {
+      content: currentContent,
+      timestamp: Date.now(),
+    }
+
+    try {
+      const result: any = await this.redis.eval(this.undoLua, {
+        keys: [keys.undo, keys.redo, keys.version],
+        arguments: [
+          JSON.stringify(currentState),
+          versionId,
+          this.TTL.toString(),
+        ],
+      })
+
+      // Check if it's an error response (table with err field)
+      if (result && typeof result === "object" && result.err) {
+        return { success: false, error: result.err }
+      }
+
+      // Success response is an array: [newVersion, previousState]
+      if (!Array.isArray(result) || result.length < 2) {
+        console.error(
+          "⏮️  HISTORY: Invalid response from undo script:",
+          result
+        )
+        return { success: false, error: "INVALID_RESPONSE" }
+      }
+
+      const [newVersion, previousStateJson] = result
+
+      if (!previousStateJson) {
+        console.error("⏮️  HISTORY: No state returned from undo script")
+        return { success: false, error: "NO_STATE_RETURNED" }
+      }
+
+      const previousState: StateData = JSON.parse(previousStateJson)
+
+      return {
+        success: true,
+        newVersion: String(newVersion),
+        content: previousState.content,
+      }
+    } catch (error: any) {
+      console.error("⏮️  HISTORY: Error performing undo:", error)
+      return { success: false, error: error.message }
+    }
+  }
+
+  /**
+   * Performs a redo operation
+   * @param courseSlug - The course slug identifier
+   * @param exerciseSlug - The exercise slug identifier
+   * @param lang - The language code
+   * @param currentContent - The current content of the state
+   * @param versionId - The version ID
+   * @returns Object containing success, newVersion, and error
+   */
+  async redo(
+    courseSlug: string,
+    exerciseSlug: string,
+    lang: string,
+    currentContent: string,
+    versionId: string
+  ): Promise<HistoryResult> {
+    const keys = this.getKeys(courseSlug, exerciseSlug, lang)
+
+    const currentState: StateData = {
+      content: currentContent,
+      timestamp: Date.now(),
+    }
+
+    try {
+      const result: any = await this.redis.eval(this.redoLua, {
+        keys: [keys.undo, keys.redo, keys.version],
+        arguments: [
+          JSON.stringify(currentState),
+          versionId,
+          this.TTL.toString(),
+        ],
+      })
+
+      // Check if it's an error response (table with err field)
+      if (result && typeof result === "object" && result.err) {
+        return { success: false, error: result.err }
+      }
+
+      // Success response is an array: [newVersion, futureState]
+      if (!Array.isArray(result) || result.length < 2) {
+        console.error(
+          "⏮️  HISTORY: Invalid response from redo script:",
+          result
+        )
+        return { success: false, error: "INVALID_RESPONSE" }
+      }
+
+      const [newVersion, futureStateJson] = result
+
+      if (!futureStateJson) {
+        console.error("⏮️  HISTORY: No state returned from redo script")
+        return { success: false, error: "NO_STATE_RETURNED" }
+      }
+
+      const futureState: StateData = JSON.parse(futureStateJson)
+
+      return {
+        success: true,
+        newVersion: String(newVersion),
+        content: futureState.content,
+      }
+    } catch (error: any) {
+      console.error("⏮️  HISTORY: Error performing redo:", error)
+      return { success: false, error: error.message }
+    }
+  }
+
+  /**
+   * Gets the history status (can undo/redo, current version)
+   * @param courseSlug - The course slug identifier
+   * @param exerciseSlug - The exercise slug identifier
+   * @param lang - The language code
+   * @returns Object containing canUndo, canRedo, and version
+   */
+  async getHistoryStatus(
+    courseSlug: string,
+    exerciseSlug: string,
+    lang: string
+  ): Promise<HistoryStatus> {
+    const keys = this.getKeys(courseSlug, exerciseSlug, lang)
+
+    try {
+      const [undoLen, redoLen, version] = await Promise.all([
+        this.redis.lLen(keys.undo),
+        this.redis.lLen(keys.redo),
+        this.redis.get(keys.version),
+      ])
+
+      return {
+        canUndo: undoLen >= 1, // Need at least 1 (we save state BEFORE changes)
+        canRedo: redoLen > 0,
+        version: version || "0",
+      }
+    } catch (error) {
+      console.error("⏮️  HISTORY: Error getting history status:", error)
+      return {
+        canUndo: false,
+        canRedo: false,
+        version: "0",
+      }
+    }
+  }
+}

package/src/managers/readmeHistoryService.ts

@@ -0,0 +1,284 @@
+import type { Bucket } from "@google-cloud/storage"
+import type { HistoryManager } from "./historyManager"
+
+export interface SaveReadmeWithHistoryOptions {
+  courseSlug: string;
+  exerciseSlug: string;
+  lang: string;
+  fileName: string;
+  newContent: string;
+  previousContent?: string; // Optional: if you already have it, pass it
+  currentVersion?: string; // Optional: if you already have it, pass it
+  throwOnConflict?: boolean; // true = throw error, false = only log
+}
+
+export interface SaveReadmeResult {
+  success: boolean;
+  newVersion: string;
+  error?: string;
+}
+
+/**
+ * Service to handle README file updates with automatic history tracking
+ * Encapsulates the logic of saving state to history before updating files
+ */
+export class ReadmeHistoryService {
+  private historyManager: HistoryManager | null
+  private bucket: Bucket
+
+  /**
+   * Constructor for the ReadmeHistoryService
+   * @param historyManager - The history manager to use
+   * @param bucket - The bucket to use
+   */
+  constructor(historyManager: HistoryManager | null, bucket: Bucket) {
+    this.historyManager = historyManager
+    this.bucket = bucket
+  }
+
+  /**
+   * Saves a README file to GCS with automatic history tracking
+   *
+   * Workflow:
+   * 1. If previousContent is not provided, downloads it from GCS
+   * 2. If currentVersion is not provided, gets it from history
+   * 3. Saves the PREVIOUS state to history (for undo)
+   * 4. Saves the NEW content to GCS
+   *
+   * @param options - Options for the saveReadmeWithHistory method
+   * @returns Result with success status and new version
+   */
+  async saveReadmeWithHistory(
+    options: SaveReadmeWithHistoryOptions
+  ): Promise<SaveReadmeResult> {
+    const {
+      courseSlug,
+      exerciseSlug,
+      lang,
+      fileName,
+      newContent,
+      previousContent: providedPreviousContent,
+      currentVersion: providedVersion,
+      throwOnConflict = false,
+    } = options
+
+    // Guard: Only process README files
+    if (!fileName.startsWith("README")) {
+      console.warn(
+        `⚠️ ReadmeHistoryService called for non-README file: ${fileName}`
+      )
+      return { success: false, newVersion: "0", error: "NOT_README_FILE" }
+    }
+
+    // Guard: History manager not available
+    if (!this.historyManager) {
+      console.warn("⚠️ History manager not available, skipping history")
+      // Still save the file without history
+      await this.saveToGCS(courseSlug, exerciseSlug, fileName, newContent)
+      return {
+        success: false,
+        newVersion: "0",
+        error: "HISTORY_NOT_AVAILABLE",
+      }
+    }
+
+    try {
+      // Step 1: Get previous content if not provided
+      const previousContent =
+        providedPreviousContent ??
+        (await this.getPreviousContent(courseSlug, exerciseSlug, fileName))
+
+      // If there's no previous content, we can't save to history
+      // (this is the first version of the file)
+      if (!previousContent) {
+        console.log(
+          `📝 HISTORY: First version of ${fileName} for ${lang}, skipping history`
+        )
+        await this.saveToGCS(courseSlug, exerciseSlug, fileName, newContent)
+        return {
+          success: false,
+          newVersion: "0",
+          error: "NO_PREVIOUS_CONTENT",
+        }
+      }
+
+      // Step 2: Get current version if not provided
+      const currentVersion =
+        providedVersion ??
+        (await this.getCurrentVersion(courseSlug, exerciseSlug, lang))
+
+      // Step 3: Save to history BEFORE updating the file
+      const historyResult = await this.historyManager.saveState(
+        courseSlug,
+        exerciseSlug,
+        lang,
+        previousContent, // Save the content BEFORE the change
+        currentVersion
+      )
+
+      // Step 4: Handle history save result
+      if (!historyResult.success) {
+        // VERSION_CONFLICT: Another user/process modified the file
+        if (historyResult.error === "VERSION_CONFLICT") {
+          const message =
+            "Version conflict detected. Content may have been modified by another process."
+
+          if (throwOnConflict) {
+            throw new Error(message)
+          } else {
+            console.error(`⏮️  HISTORY: ${message}`)
+            // Still save the file despite conflict
+            await this.saveToGCS(
+              courseSlug,
+              exerciseSlug,
+              fileName,
+              newContent
+            )
+            return {
+              success: false,
+              newVersion: currentVersion,
+              error: "VERSION_CONFLICT",
+            }
+          }
+        }
+
+        // Other errors: log but don't fail
+        console.error(
+          `⏮️  HISTORY: Failed to save history (non-critical): ${historyResult.error}`
+        )
+        await this.saveToGCS(courseSlug, exerciseSlug, fileName, newContent)
+        return {
+          success: false,
+          newVersion: currentVersion,
+          error: historyResult.error,
+        }
+      }
+
+      // Step 5: History saved successfully, now save the new content
+      await this.saveToGCS(courseSlug, exerciseSlug, fileName, newContent)
+
+      console.log(
+        `✅ HISTORY: Saved ${fileName} (${lang}) - version ${historyResult.newVersion}`
+      )
+
+      return {
+        success: true,
+        newVersion: historyResult.newVersion!,
+      }
+    } catch (error: any) {
+      const errorMessage = error.message || "Unknown error"
+      console.error(
+        `❌ HISTORY: Error in saveReadmeWithHistory: ${errorMessage}`
+      )
+
+      // Try to save the file anyway (best effort)
+      try {
+        await this.saveToGCS(courseSlug, exerciseSlug, fileName, newContent)
+      } catch (saveError) {
+        console.error("❌ Failed to save file after history error:", saveError)
+      }
+
+      return {
+        success: false,
+        newVersion: "0",
+        error: errorMessage,
+      }
+    }
+  }
+
+  /**
+   * Gets the previous content of a README from GCS
+   * Returns undefined if file doesn't exist (first version)
+   * @param courseSlug - The slug of the course
+   * @param exerciseSlug - The slug of the exercise
+   * @param fileName - The name of the file
+   * @returns The previous content of the file or undefined if it doesn't exist
+   */
+  private async getPreviousContent(
+    courseSlug: string,
+    exerciseSlug: string,
+    fileName: string
+  ): Promise<string | undefined> {
+    try {
+      const filePath = `courses/${courseSlug}/exercises/${exerciseSlug}/${fileName}`
+      const [content] = await this.bucket.file(filePath).download()
+      return content.toString()
+    } catch (error: any) {
+      // File doesn't exist (404) - this is normal for first save
+      if (error.code === 404) {
+        return undefined
+      }
+
+      console.error(`⚠️ Error downloading previous content: ${error.message}`)
+      return undefined
+    }
+  }
+
+  /**
+   * Gets the current version from history
+   * @param courseSlug - The slug of the course
+   * @param exerciseSlug - The slug of the exercise
+   * @param lang - The language of the file
+   * @returns The current version of the file
+   */
+  private async getCurrentVersion(
+    courseSlug: string,
+    exerciseSlug: string,
+    lang: string
+  ): Promise<string> {
+    if (!this.historyManager) {
+      return "0"
+    }
+
+    try {
+      const status = await this.historyManager.getHistoryStatus(
+        courseSlug,
+        exerciseSlug,
+        lang
+      )
+      return status.version
+    } catch (error) {
+      console.error(
+        "⚠️ Error getting current version, defaulting to '0':",
+        error
+      )
+      return "0"
+    }
+  }
+
+  /**
+   * Saves content to Google Cloud Storage
+   * @param courseSlug - The slug of the course
+   * @param exerciseSlug - The slug of the exercise
+   * @param fileName - The name of the file
+   * @param content - The content to save
+   * @returns void
+   */
+  private async saveToGCS(
+    courseSlug: string,
+    exerciseSlug: string,
+    fileName: string,
+    content: string
+  ): Promise<void> {
+    const filePath = `courses/${courseSlug}/exercises/${exerciseSlug}/${fileName}`
+    const file = this.bucket.file(filePath)
+
+    await file.save(content, {
+      resumable: false,
+    })
+  }
+
+  /**
+   * Helper to get README extension from language code
+   * @param lang - The language of the file
+   * @returns The name of the README file
+   */
+  static getReadmeFileName(lang: string): string {
+    if (lang === "en") {
+      return "README.md"
+    }
+
+    // es -> README.es.md, fr -> README.fr.md
+    return `README.${lang}.md`
+  }
+}