@learnpack/learnpack 5.0.342 → 5.0.344

package/src/commands/serve.ts

@@ -174,6 +174,244 @@ const uploadFileToBucket = async (
   await fileRef.save(Buffer.from(content, "utf8"))
 }
 
+const uploadBinaryToBucket = async (
+  bucket: Bucket,
+  buffer: Buffer,
+  path: string,
+  contentType?: string
+) => {
+  const fileRef = bucket.file(path)
+  await fileRef.save(buffer, {
+    resumable: false,
+    ...(contentType && { contentType }),
+  })
+}
+
+const getGithubCredentials = () => {
+  const token = process.env.GITHUB_TOKEN?.trim()
+  const username = process.env.GITHUB_USERNAME?.trim()
+  return { token, username, isConfigured: Boolean(token && username) }
+}
+
+type GithubOperation =
+  | "create_repo"
+  | "get_base_ref"
+  | "create_blob"
+  | "create_tree"
+  | "create_commit"
+  | "update_ref";
+
+type GithubCallContext = {
+  operation: GithubOperation;
+  repository?: string;
+  failedPath?: string;
+  repoCreated?: boolean;
+  repoName?: string;
+  retryOnUnavailableConflict?: boolean;
+};
+
+const GITHUB_RETRY_DELAYS_MS = [250, 600, 1200]
+
+const wait = (ms: number) =>
+  new Promise<void>(resolve => {
+    setTimeout(resolve, ms)
+  })
+
+const getGithubErrorStatus = (error: any): number | undefined =>
+  error?.response?.status
+
+const getGithubErrorData = (error: any): any => error?.response?.data || {}
+
+const getGithubErrorMessage = (error: any): string | undefined => {
+  const data = getGithubErrorData(error)
+  if (typeof data?.message === "string") {
+    return data.message
+  }
+
+  if (typeof error?.message === "string") {
+    return error.message
+  }
+
+  return undefined
+}
+
+const errorPayloadHasText = (payload: unknown, term: string): boolean => {
+  if (!payload || !term) return false
+
+  try {
+    return JSON.stringify(payload).toLowerCase().includes(term.toLowerCase())
+  } catch {
+    return false
+  }
+}
+
+const isGithubPushProtectionConflict = (error: any): boolean => {
+  if (getGithubErrorStatus(error) !== 409) return false
+
+  const message = (getGithubErrorMessage(error) || "").toLowerCase()
+  const data = getGithubErrorData(error)
+
+  return (
+    message.includes("push protection") ||
+    message.includes("secret scanning") ||
+    message.includes("secret") ||
+    errorPayloadHasText(data?.errors, "push protection") ||
+    errorPayloadHasText(data?.errors, "secret")
+  )
+}
+
+const isGithubRepoUnavailableConflict = (error: any): boolean => {
+  if (getGithubErrorStatus(error) !== 409) return false
+
+  const message = (getGithubErrorMessage(error) || "").toLowerCase()
+  return (
+    message.includes("empty or unavailable") ||
+    message.includes("repository is empty") ||
+    message.includes("repository is unavailable") ||
+    message.includes("currently being created")
+  )
+}
+
+const shouldRetryGithubConflict = (error: any): boolean =>
+  isGithubRepoUnavailableConflict(error) &&
+  !isGithubPushProtectionConflict(error)
+
+const toGithubOperationalError = (
+  error: any,
+  context: GithubCallContext
+): Error => {
+  if (error?.isOperational === true) {
+    return error
+  }
+
+  const status = getGithubErrorStatus(error)
+  const data = getGithubErrorData(error)
+  const githubMessage = getGithubErrorMessage(error)
+  const details = {
+    failedOperation: context.operation,
+    ...(context.failedPath ? { failedPath: context.failedPath } : {}),
+    ...(context.repository ? { repository: context.repository } : {}),
+    ...(context.repoCreated ? { repoCreated: true } : {}),
+    github: {
+      status,
+      message: githubMessage,
+      documentation_url: data?.documentation_url,
+      errors: data?.errors,
+    },
+  }
+
+  let message =
+    githubMessage ||
+    `GitHub request failed during operation "${context.operation}"`
+
+  if (status === 422 && context.operation === "create_repo") {
+    message = context.repoName ?
+      `Repository "${context.repoName}" may already exist or name is invalid` :
+      "Repository may already exist or the requested name is invalid"
+  } else if (status === 409 && isGithubPushProtectionConflict(error)) {
+    message = context.failedPath ?
+      `File blocked by push protection: ${context.failedPath}` :
+      "GitHub push protection blocked sensitive content during the initial commit"
+  } else if (context.repoCreated && context.operation !== "create_repo") {
+    message =
+      "Repo created on GitHub, but the initial commit failed. Check the details and try again."
+  }
+
+  if (status === 400) return new ValidationError(message, details)
+  if (status === 404) return new NotFoundError(message, details)
+  if (status === 409 || status === 422)
+    return new ConflictError(message, details)
+
+  return new InternalServerError(message, details)
+}
+
+const githubApiFetch = async (
+  url: string,
+  token: string,
+  options: { method?: string; body?: unknown } = {}
+) => {
+  const res = await axios({
+    url,
+    method: options.method || "GET",
+    headers: {
+      Authorization: `token ${token}`,
+      Accept: "application/vnd.github.v3+json",
+    },
+    data: options.body,
+  })
+  return res.data
+}
+
+const githubApiFetchWithContext = async (
+  url: string,
+  token: string,
+  context: GithubCallContext,
+  options: { method?: string; body?: unknown } = {}
+) => {
+  try {
+    return await githubApiFetch(url, token, options)
+  } catch (error) {
+    throw toGithubOperationalError(error, context)
+  }
+}
+
+const githubApiFetchWithRetry = async (
+  url: string,
+  token: string,
+  context: GithubCallContext,
+  options: { method?: string; body?: unknown } = {}
+) => {
+  const attempts = context.retryOnUnavailableConflict ?
+    GITHUB_RETRY_DELAYS_MS.length + 1 :
+    1
+
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try {
+      // eslint-disable-next-line no-await-in-loop -- Sequential processing to avoid rate limits
+      return await githubApiFetch(url, token, options)
+    } catch (error) {
+      const canRetry =
+        attempt < attempts - 1 && shouldRetryGithubConflict(error)
+      if (!canRetry) {
+        throw toGithubOperationalError(error, context)
+      }
+
+      // eslint-disable-next-line no-await-in-loop -- Sequential processing to avoid rate limits
+      await wait(GITHUB_RETRY_DELAYS_MS[attempt])
+    }
+  }
+
+  throw new InternalServerError("GitHub request failed after retries", {
+    failedOperation: context.operation,
+    repository: context.repository,
+  })
+}
+
+const mapWithConcurrency = async <T, R>(
+  items: T[],
+  limit: number,
+  mapper: (item: T, index: number) => Promise<R>
+): Promise<R[]> => {
+  if (items.length === 0) {
+    return []
+  }
+
+  const concurrency = Math.max(1, Math.min(limit, items.length))
+  const results = Array.from({ length: items.length }) as R[]
+  let cursor = 0
+
+  const worker = async () => {
+    let index
+    while ((index = cursor++) < items.length) {
+      // eslint-disable-next-line no-await-in-loop -- intentional: each worker processes items sequentially
+      results[index] = await mapper(items[index], index)
+    }
+  }
+
+  await Promise.all(Array.from({ length: concurrency }, () => worker()))
+  return results
+}
+
 const PARAMS = {
   expected_grade_level: "8",
   max_fkgl: 10,
@@ -592,6 +830,23 @@ const getConfigJSON = async (bucket: Bucket, courseSlug: string) => {
   return JSON.parse(content.toString())
 }
 
+async function mergeConfigPreservingGithub(
+  bucket: Bucket,
+  courseSlug: string,
+  newConfig: Record<string, unknown>
+): Promise<Record<string, unknown>> {
+  try {
+    const existing = await getConfigJSON(bucket, courseSlug)
+    if (existing?.config?.github) {
+      return { ...newConfig, github: { ...existing.config.github } }
+    }
+  } catch {
+    // No existing config or parse error - use newConfig as-is
+  }
+
+  return newConfig
+}
+
 async function getSyllabus(
   courseSlug: string,
   bucket: Bucket
@@ -1647,9 +1902,12 @@ class ServeCommand extends SessionCommand {
                 try {
                   console.log(`📄 Processing file: ${fileObj.name}`)
 
+                  // Flatten path: use only the file name so files are stored directly in the exercise folder
+                  const flatFileName = path.basename(fileObj.name)
+
                   // Save the main file with content
                   if (fileObj.name && fileObj.content) {
-                    const filePath = `${exerciseDir}/${fileObj.name}`
+                    const filePath = `${exerciseDir}/${flatFileName}`
                     // eslint-disable-next-line no-await-in-loop
                     await uploadFileToBucket(bucket, fileObj.content, filePath)
                     console.log(`✅ Saved file: ${filePath}`)
@@ -1657,7 +1915,7 @@ class ServeCommand extends SessionCommand {
 
                   // Save the solution file if it exists
                   if (fileObj.name && fileObj.solution) {
-                    const nameParts = fileObj.name.split(".")
+                    const nameParts = flatFileName.split(".")
                     if (nameParts.length > 1) {
                       const extension = nameParts.pop()
                       const baseName = nameParts.join(".")
@@ -1674,7 +1932,7 @@ class ServeCommand extends SessionCommand {
                       )
                     } else {
                       // If no extension, just add .solution.hide
-                      const solutionFileName = `${fileObj.name}.solution.hide`
+                      const solutionFileName = `${flatFileName}.solution.hide`
                       const solutionFilePath = `${exerciseDir}/${solutionFileName}`
                       // eslint-disable-next-line no-await-in-loop
                       await uploadFileToBucket(
@@ -2823,7 +3081,16 @@ class ServeCommand extends SessionCommand {
       }
 
       try {
-        const { config, exercises } = await buildConfig(bucket, courseSlug)
+        const { config: builtConfig, exercises } = await buildConfig(
+          bucket,
+          courseSlug
+        )
+        const config = await mergeConfigPreservingGithub(
+          bucket,
+          courseSlug,
+          builtConfig
+        )
+
         res.set("X-Creator-Web", "true")
         res.set("Access-Control-Expose-Headers", "X-Creator-Web")
 
@@ -2975,21 +3242,24 @@ class ServeCommand extends SessionCommand {
           throw new ValidationError("File name and exercise slug are required")
         }
 
-        // Extract content from body (can be text or JSON)
-        let fileContent: string
-        let contentToSaveInHistory: string | undefined
-
-        if (typeof req.body === "string") {
-          // Old format: plain text
-          fileContent = req.body
-        } else if (req.body && typeof req.body === "object") {
-          // New format: JSON with content and historyContent
-          fileContent = req.body.content
-          contentToSaveInHistory = req.body.historyContent
-        } else {
-          throw new ValidationError("Invalid request body format")
+        // Require JSON body with content field; return 400 with clear message otherwise
+        if (
+          !req.body ||
+          typeof req.body !== "object" ||
+          req.body.content === undefined
+        ) {
+          throw new ValidationError(
+            'Request body must be JSON with a \'content\' field. Use Content-Type: application/json and body: { "content": "..." }.'
+          )
         }
 
+        const fileContent = String(req.body.content)
+        const contentToSaveInHistory =
+          req.body.historyContent !== null &&
+          req.body.historyContent !== undefined ?
+            String(req.body.historyContent) :
+            undefined
+
         try {
           let newVersion = versionId
           let created = false
@@ -4434,6 +4704,8 @@ class ServeCommand extends SessionCommand {
           title: string;
           slug: string;
         }> = []
+        let repairedTranslationsInLessons = 0
+        let repairedTranslationEntries = 0
 
         console.log(
           `📋 Checking ${syllabus.lessons.length} lessons in syllabus...`
@@ -4615,10 +4887,82 @@ class ServeCommand extends SessionCommand {
           })
         }
 
-        if (totalRemoved > 0 || addedLessons.length > 0) {
+        // Fourth pass: reconcile lesson.translations from actual README files in bucket.
+        // This fixes lessons that exist but lost translations metadata after renames or syncs.
+        try {
+          const { exercises } = await buildConfig(bucket, courseSlug)
+          const translationsBySlug = new Map<string, string[]>()
+
+          for (const exercise of exercises) {
+            const langs = Object.keys(exercise.translations || {})
+              .map(lang => lang.toLowerCase())
+              .filter(Boolean)
+            if (langs.length > 0) {
+              translationsBySlug.set(exercise.slug, [...new Set(langs)])
+            }
+          }
+
+          for (const lesson of syllabus.lessons) {
+            const candidateSlugs = [
+              slugify(lesson.id + "-" + lesson.title),
+              lesson.uid,
+            ].filter(Boolean)
+            const matchedSlug = candidateSlugs.find(s =>
+              translationsBySlug.has(s)
+            )
+            if (!matchedSlug) continue
+
+            const languageCodes = translationsBySlug.get(matchedSlug) || []
+            if (languageCodes.length === 0) continue
+
+            const currentTranslations = lesson.translations || {}
+            let lessonChanged = false
+
+            for (const lang of languageCodes) {
+              const now = Date.now()
+              if (!currentTranslations[lang]) {
+                currentTranslations[lang] = {
+                  completionId: 0,
+                  startedAt: now,
+                  completedAt: now,
+                }
+                repairedTranslationEntries += 1
+                lessonChanged = true
+              } else {
+                // If README exists for this language but metadata is incomplete, mark it as completed.
+                if (!currentTranslations[lang].startedAt) {
+                  currentTranslations[lang].startedAt = now
+                  lessonChanged = true
+                }
+
+                if (!currentTranslations[lang].completedAt) {
+                  currentTranslations[lang].completedAt = now
+                  repairedTranslationEntries += 1
+                  lessonChanged = true
+                }
+              }
+            }
+
+            if (lessonChanged) {
+              lesson.translations = currentTranslations
+              repairedTranslationsInLessons += 1
+            }
+          }
+        } catch (error) {
+          console.error(
+            "⚠️ Could not reconcile lesson translations during syllabus sync:",
+            error
+          )
+        }
+
+        if (
+          totalRemoved > 0 ||
+          addedLessons.length > 0 ||
+          repairedTranslationsInLessons > 0
+        ) {
           await saveSyllabus(courseSlug, syllabus, bucket)
           console.log(
-            `✅ Syllabus synchronized. Removed ${removedLessons.length} non-existent, ${duplicatesRemoved.length} duplicate(s); added ${addedLessons.length} from bucket.`
+            `✅ Syllabus synchronized. Removed ${removedLessons.length} non-existent, ${duplicatesRemoved.length} duplicate(s); added ${addedLessons.length} from bucket; repaired translations in ${repairedTranslationsInLessons} lesson(s).`
           )
         } else {
           console.log(`✅ Syllabus is already in sync. No changes.`)
@@ -4632,6 +4976,8 @@ class ServeCommand extends SessionCommand {
           removedLessons: removedLessons.length,
           duplicatesResolved: duplicatesRemoved.length,
           addedLessons: addedLessons.length,
+          repairedTranslationsInLessons,
+          repairedTranslationEntries,
           removed: removedLessons,
           duplicates: duplicatesRemoved,
           kept: keptLessons,
@@ -4646,6 +4992,142 @@ class ServeCommand extends SessionCommand {
       }
     })
 
+    app.post("/actions/synchronize-lesson-files", async (req, res) => {
+      const courseSlug = req.query.slug as string
+      const { lessonSlug } = req.body || {}
+
+      if (!courseSlug || !lessonSlug) {
+        return res.status(400).json({
+          error: "Course slug (query) and lessonSlug (body) are required",
+        })
+      }
+
+      try {
+        const configJson = await getConfigJSON(bucket, courseSlug)
+        const exercises = configJson.exercises as Array<{
+          slug: string;
+          files: Array<{ name: string; slug?: string; hidden?: boolean }>;
+        }>
+        const exercise = exercises.find(ex => ex.slug === lessonSlug)
+
+        if (!exercise) {
+          return res.status(404).json({
+            error: `Lesson not found: ${lessonSlug}`,
+          })
+        }
+
+        const initialCount = exercise.files?.length ?? 0
+        if (initialCount === 0) {
+          return res.json({
+            status: "SUCCESS",
+            removedCount: 0,
+            keptCount: 0,
+            movedCount: 0,
+          })
+        }
+
+        const lessonPrefix = `courses/${courseSlug}/exercises/${lessonSlug}/`
+        const [bucketObjects] = await bucket.getFiles({ prefix: lessonPrefix })
+
+        const existenceChecks = await Promise.all(
+          exercise.files.map(async file => {
+            const flatPath = `${lessonPrefix}${file.name}`
+            const [existsAtFlat] = await bucket.file(flatPath).exists()
+            return { file, flatPath, existsAtFlat }
+          })
+        )
+
+        const kept: typeof exercise.files = []
+        const notFoundInBucket: string[] = []
+        const toMove: Array<{
+          file: typeof exercise.files[0];
+          subdirPath: string;
+          flatPath: string;
+        }> = []
+
+        for (const { file, flatPath, existsAtFlat } of existenceChecks) {
+          if (existsAtFlat) {
+            kept.push(file)
+            continue
+          }
+
+          const subdirObject = bucketObjects.find(obj => {
+            if (!obj.name.endsWith(`/${file.name}`)) return false
+            const afterLesson = obj.name.slice(lessonPrefix.length)
+            const segments = afterLesson.split("/")
+            return (
+              segments.length === 2 &&
+              segments[0] !== "" &&
+              segments[0] !== ".learn"
+            )
+          })
+          if (subdirObject) {
+            toMove.push({ file, subdirPath: subdirObject.name, flatPath })
+          } else {
+            notFoundInBucket.push(file.name)
+          }
+        }
+
+        let movedCount = 0
+        if (toMove.length > 0) {
+          await Promise.all(
+            toMove.map(async ({ file, subdirPath, flatPath }) => {
+              const srcFile = bucket.file(subdirPath)
+              const destFile = bucket.file(flatPath)
+              await srcFile.copy(destFile)
+              await srcFile.delete()
+            })
+          )
+          for (const { file } of toMove) {
+            kept.push(file)
+          }
+
+          movedCount = toMove.length
+
+          const subdirName = toMove[0].subdirPath
+            .slice(lessonPrefix.length)
+            .split("/")[0]
+          const subdirPrefix = `${lessonPrefix}${subdirName}/`
+          const [remainingInSubdir] = await bucket.getFiles({
+            prefix: subdirPrefix,
+          })
+          if (remainingInSubdir.length > 0) {
+            await Promise.all(remainingInSubdir.map(f => f.delete()))
+          }
+        }
+
+        const removedCount = initialCount - kept.length
+        exercise.files = kept
+
+        if (removedCount > 0) {
+          await uploadFileToBucket(
+            bucket,
+            JSON.stringify({ config: configJson.config, exercises }),
+            `courses/${courseSlug}/.learn/config.json`
+          )
+        }
+
+        if (movedCount > 0 || removedCount > 0) {
+          console.log(
+            `[sync-lesson-files] ${lessonSlug}: ${movedCount} moved from subdir, ${removedCount} removed from config`
+          )
+        }
+
+        res.json({
+          status: "SUCCESS",
+          removedCount,
+          keptCount: kept.length,
+          movedCount,
+        })
+      } catch (error) {
+        console.error("❌ Error synchronizing lesson files:", error)
+        res.status(500).json({
+          error: "Error synchronizing lesson files",
+          details: (error as Error).message,
+        })
+      }
+    })
+
     app.get("/translations/sidebar", async (req, res) => {
       const { slug } = req.query
 
@@ -5662,6 +6144,817 @@ class ServeCommand extends SessionCommand {
       }
     })
 
+    app.get("/actions/github/status", async (req, res) => {
+      const courseSlug = req.query.slug as string
+      if (!courseSlug) {
+        return res
+          .status(400)
+          .json({ error: "slug query parameter is required" })
+      }
+
+      const { isConfigured } = getGithubCredentials()
+
+      try {
+        const configJson = await getConfigJSON(bucket, courseSlug)
+        const github = configJson.config?.github
+        const repository = github?.repository
+        const linked = Boolean(repository)
+
+        return res.json({
+          configured: isConfigured,
+          linked,
+          repository: linked ? repository : null,
+        })
+      } catch {
+        return res.json({
+          configured: isConfigured,
+          linked: false,
+          repository: null,
+        })
+      }
+    })
+
+    app.post(
+      "/actions/github/create-repo",
+      express.json(),
+      asyncHandler(async (req, res) => {
+        const { courseSlug, repoName, isPrivate, description } = req.body
+
+        if (!courseSlug) {
+          throw new ValidationError("courseSlug is required in request body")
+        }
+
+        const { token, username, isConfigured } = getGithubCredentials()
+        if (!isConfigured || !token || !username) {
+          throw new ValidationError(
+            "GitHub credentials not configured. Set GITHUB_TOKEN and GITHUB_USERNAME in .env"
+          )
+        }
+
+        const configJson = await getConfigJSON(bucket, courseSlug)
+        if (configJson.config?.github?.repository) {
+          throw new ConflictError(
+            "Package already has a linked GitHub repository"
+          )
+        }
+
+        const finalRepoName = repoName || courseSlug
+        const finalDescription =
+          description || "Tutorial created with LearnPack"
+
+        const createRepoUrl = "https://api.github.com/user/repos"
+        const createdRepo = await githubApiFetchWithContext(
+          createRepoUrl,
+          token,
+          {
+            operation: "create_repo",
+            repoName: finalRepoName,
+          },
+          {
+            method: "POST",
+            body: {
+              name: finalRepoName,
+              private: Boolean(isPrivate),
+              description: finalDescription,
+              auto_init: true,
+            },
+          }
+        )
+
+        const repository =
+          createdRepo?.full_name || `${username}/${finalRepoName}`
+        const defaultBranch = createdRepo?.default_branch || "main"
+        const repositoryUrl =
+          createdRepo?.html_url || `https://github.com/${repository}`
+
+        const refRes = await githubApiFetchWithRetry(
+          `https://api.github.com/repos/${repository}/git/ref/heads/${defaultBranch}`,
+          token,
+          {
+            operation: "get_base_ref",
+            repository,
+            repoCreated: true,
+            retryOnUnavailableConflict: true,
+          },
+          {}
+        )
+        const baseSHA =
+          refRes.object?.sha ?? refRes.ref?.object?.sha ?? refRes.object?.sha
+        if (!baseSHA) {
+          throw new InternalServerError(
+            "Could not get default branch SHA from GitHub after repository creation",
+            {
+              failedOperation: "get_base_ref",
+              repository,
+              repoCreated: true,
+            }
+          )
+        }
+
+        const [allFiles] = await bucket.getFiles({
+          prefix: `courses/${courseSlug}/`,
+        })
+
+        const treeEntries = await mapWithConcurrency(
+          allFiles,
+          5,
+          async file => {
+            const relativePath = file.name.replace(
+              `courses/${courseSlug}/`,
+              ""
+            )
+            const [content] = await file.download()
+            const contentBase64 = content.toString("base64")
+
+            const blobRes = await githubApiFetchWithRetry(
+              `https://api.github.com/repos/${repository}/git/blobs`,
+              token,
+              {
+                operation: "create_blob",
+                repository,
+                failedPath: relativePath,
+                repoCreated: true,
+                retryOnUnavailableConflict: true,
+              },
+              {
+                method: "POST",
+                body: { content: contentBase64, encoding: "base64" },
+              }
+            )
+
+            return {
+              path: relativePath,
+              mode: "100644",
+              type: "blob",
+              sha: blobRes.sha,
+            }
+          }
+        )
+
+        const treeRes = await githubApiFetchWithRetry(
+          `https://api.github.com/repos/${repository}/git/trees`,
+          token,
+          {
+            operation: "create_tree",
+            repository,
+            repoCreated: true,
+            retryOnUnavailableConflict: true,
+          },
+          {
+            method: "POST",
+            body: { tree: treeEntries },
+          }
+        )
+
+        const commitRes = await githubApiFetchWithRetry(
+          `https://api.github.com/repos/${repository}/git/commits`,
+          token,
+          {
+            operation: "create_commit",
+            repository,
+            repoCreated: true,
+            retryOnUnavailableConflict: true,
+          },
+          {
+            method: "POST",
+            body: {
+              message: "Initial commit from LearnPack",
+              tree: treeRes.sha,
+              parents: [baseSHA],
+            },
+          }
+        )
+
+        await githubApiFetchWithRetry(
+          `https://api.github.com/repos/${repository}/git/refs/heads/${defaultBranch}`,
+          token,
+          {
+            operation: "update_ref",
+            repository,
+            repoCreated: true,
+            retryOnUnavailableConflict: true,
+          },
+          {
+            method: "PATCH",
+            body: {
+              sha: commitRes.sha,
+              force: false,
+            },
+          }
+        )
+
+        configJson.config = configJson.config || {}
+        configJson.config.github = {
+          repository,
+          defaultBranch,
+          lastSyncSHA: commitRes.sha,
+        }
+        await uploadFileToBucket(
+          bucket,
+          JSON.stringify(configJson),
+          `courses/${courseSlug}/.learn/config.json`
+        )
+
+        return res.json({
+          success: true,
+          repository,
+          url: repositoryUrl,
+          sha: commitRes.sha,
+        })
+      })
+    )
+
+    const GITHUB_STRUCTURAL_FILES = new Set([
+      "learn.json",
+      ".learn/config.json",
+      ".learn/initialSyllabus.json",
+      ".learn/sidebar.json",
+      ".learn/memory_bank.txt",
+    ])
+
+    const isStructuralFile = (relativePath: string) =>
+      GITHUB_STRUCTURAL_FILES.has(relativePath) ||
+      relativePath === "learn.json" ||
+      (relativePath.startsWith(".learn/") &&
+        !relativePath.startsWith(".learn/assets/"))
+
+    const IMAGE_EXTENSIONS = [".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp"]
+
+    const isImageFile = (path: string) =>
+      IMAGE_EXTENSIONS.some(ext => path.toLowerCase().endsWith(ext))
+
+    app.get(
+      "/actions/github/check-changes",
+      asyncHandler(async (req, res) => {
+        const courseSlug = req.query.slug as string
+        if (!courseSlug) {
+          throw new ValidationError("slug query parameter is required")
+        }
+
+        const { token, isConfigured } = getGithubCredentials()
+        if (!isConfigured || !token) {
+          throw new ValidationError(
+            "GitHub credentials not configured. Set GITHUB_TOKEN and GITHUB_USERNAME in .env"
+          )
+        }
+
+        const configJson = await getConfigJSON(bucket, courseSlug)
+        const repository = configJson.config?.github?.repository
+        const lastSyncSHA = configJson.config?.github?.lastSyncSHA
+        const defaultBranch =
+          configJson.config?.github?.defaultBranch || "main"
+
+        if (!repository || !lastSyncSHA) {
+          throw new ValidationError(
+            "Package has no linked GitHub repository. Create one first."
+          )
+        }
+
+        const refRes = await githubApiFetch(
+          `https://api.github.com/repos/${repository}/git/ref/heads/${defaultBranch}`,
+          token
+        )
+        const currentBranchSHA =
+          refRes.object?.sha ?? refRes.ref?.object?.sha ?? refRes.object?.sha
+        if (!currentBranchSHA) {
+          throw new ValidationError(
+            `Could not get ${defaultBranch} branch SHA from GitHub`
+          )
+        }
+
+        const compareRes = await githubApiFetch(
+          `https://api.github.com/repos/${repository}/compare/${lastSyncSHA}...${currentBranchSHA}`,
+          token
+        )
+
+        if (
+          compareRes.status === "identical" ||
+          !compareRes.files ||
+          compareRes.files.length === 0
+        ) {
+          return res.json({ hasChanges: false })
+        }
+
+        const [allExerciseFiles] = await bucket.getFiles({
+          prefix: `courses/${courseSlug}/exercises/`,
+        })
+
+        const lessonSlugs = new Set<string>()
+        const lessonFilesMap = new Map<string, Set<string>>()
+
+        for (const file of allExerciseFiles) {
+          const match = file.name.match(
+            new RegExp(`courses/${courseSlug}/exercises/([^/]+)/(.+)$`)
+          )
+          if (match) {
+            const [, slug, filePart] = match
+            lessonSlugs.add(slug)
+            if (!lessonFilesMap.has(slug)) {
+              lessonFilesMap.set(slug, new Set())
+            }
+
+            lessonFilesMap.get(slug)!.add(filePart)
+          }
+        }
+
+        const syncableLessons: Array<{
+          slug: string;
+          files: Array<{ filename: string; status: string }>;
+        }> = []
+        const syncableAssets: Array<{ filename: string; status: string }> = []
+        const skippedFiles: Array<{
+          filename: string;
+          status: string;
+          reason: string;
+        }> = []
+
+        for (const f of compareRes.files) {
+          const relativePath = f.filename
+          const status = f.status || "modified"
+
+          if (isStructuralFile(relativePath)) {
+            skippedFiles.push({
+              filename: relativePath,
+              status,
+              reason: "Structural file",
+            })
+            continue
+          }
+
+          const exercisesMatch = relativePath.match(
+            /^exercises\/([^/]+)\/(.+)$/
+          )
+          if (exercisesMatch) {
+            const [, slug, filename] = exercisesMatch
+            if (!lessonSlugs.has(slug)) {
+              skippedFiles.push({
+                filename: relativePath,
+                status,
+                reason: "Lesson does not exist in bucket",
+              })
+              continue
+            }
+
+            const existingFiles = lessonFilesMap.get(slug)!
+            if (status !== "modified" || !existingFiles.has(filename)) {
+              skippedFiles.push({
+                filename: relativePath,
+                status,
+                reason:
+                  status === "modified" ?
+                    "File does not exist in bucket (only modified existing files are synced)" :
+                    "Structural change in lesson (only modified files are synced)",
+              })
+              continue
+            }
+
+            let lessonEntry = syncableLessons.find(l => l.slug === slug)
+            if (!lessonEntry) {
+              lessonEntry = { slug, files: [] }
+              syncableLessons.push(lessonEntry)
+            }
+
+            lessonEntry.files.push({ filename, status })
+            continue
+          }
+
+          if (relativePath.startsWith(".learn/assets/")) {
+            syncableAssets.push({ filename: relativePath, status })
+            continue
+          }
+
+          skippedFiles.push({
+            filename: relativePath,
+            status,
+            reason: "Unknown path",
+          })
+        }
+
+        return res.json({
+          hasChanges: true,
+          currentSHA: currentBranchSHA,
+          lastSyncSHA,
+          syncableChanges: {
+            lessons: syncableLessons,
+            assets: syncableAssets,
+            totalFiles:
+              syncableLessons.reduce((s, l) => s + l.files.length, 0) +
+              syncableAssets.length,
+          },
+          skippedChanges: {
+            files: skippedFiles,
+            totalFiles: skippedFiles.length,
+          },
+        })
+      })
+    )
+
+    app.post(
+      "/actions/github/pull",
+      express.json(),
+      asyncHandler(async (req, res) => {
+        const { courseSlug, targetSHA, lessons } = req.body
+
+        if (!courseSlug || !targetSHA) {
+          throw new ValidationError(
+            "courseSlug and targetSHA are required in request body"
+          )
+        }
+
+        const { token, isConfigured } = getGithubCredentials()
+        if (!isConfigured || !token) {
+          throw new ValidationError(
+            "GitHub credentials not configured. Set GITHUB_TOKEN and GITHUB_USERNAME in .env"
+          )
+        }
+
+        const configJson = await getConfigJSON(bucket, courseSlug)
+        const repository = configJson.config?.github?.repository
+        const lastSyncSHA = configJson.config?.github?.lastSyncSHA
+
+        if (!repository || !lastSyncSHA) {
+          throw new ValidationError(
+            "Package has no linked GitHub repository. Create one first."
+          )
+        }
+
+        const [allExerciseFiles] = await bucket.getFiles({
+          prefix: `courses/${courseSlug}/exercises/`,
+        })
+
+        const lessonSlugs = new Set<string>()
+        const lessonFilesMap = new Map<string, Set<string>>()
+
+        for (const file of allExerciseFiles) {
+          const match = file.name.match(
+            new RegExp(`courses/${courseSlug}/exercises/([^/]+)/(.+)$`)
+          )
+          if (match) {
+            const [, slug, filePart] = match
+            lessonSlugs.add(slug)
+            if (!lessonFilesMap.has(slug)) {
+              lessonFilesMap.set(slug, new Set())
+            }
+
+            lessonFilesMap.get(slug)!.add(filePart)
+          }
+        }
+
+        const compareRes = await githubApiFetch(
+          `https://api.github.com/repos/${repository}/compare/${lastSyncSHA}...${targetSHA}`,
+          token
+        )
+
+        if (
+          compareRes.status === "identical" ||
+          !compareRes.files ||
+          compareRes.files.length === 0
+        ) {
+          configJson.config = configJson.config || {}
+          configJson.config.github = {
+            ...configJson.config.github,
+            lastSyncSHA: targetSHA,
+          }
+          await uploadFileToBucket(
+            bucket,
+            JSON.stringify(configJson),
+            `courses/${courseSlug}/.learn/config.json`
+          )
+          return res.json({
+            success: true,
+            syncedLessons: [],
+            syncedAssets: 0,
+            syncedFiles: 0,
+            removedFiles: 0,
+            skippedFiles: [],
+            newSHA: targetSHA,
+          })
+        }
+
+        const lessonFilter =
+          Array.isArray(lessons) && lessons.length > 0 ?
+            new Set(lessons as string[]) :
+            null
+
+        const toSync: Array<{
+          relativePath: string;
+          status: string;
+          bucketPath: string;
+          isAsset: boolean;
+          previousBucketPath?: string;
+        }> = []
+        const skippedFiles: Array<{
+          filename: string;
+          status: string;
+          reason: string;
+        }> = []
+
+        for (const f of compareRes.files) {
+          const relativePath = f.filename
+          const status = f.status || "modified"
+
+          if (isStructuralFile(relativePath)) {
+            skippedFiles.push({
+              filename: relativePath,
+              status,
+              reason: "Structural file",
+            })
+            continue
+          }
+
+          const exercisesMatch = relativePath.match(
+            /^exercises\/([^/]+)\/(.+)$/
+          )
+          if (exercisesMatch) {
+            const [, slug, filename] = exercisesMatch
+            if (lessonFilter && !lessonFilter.has(slug)) continue
+            if (!lessonSlugs.has(slug)) {
+              skippedFiles.push({
+                filename: relativePath,
+                status,
+                reason: "Lesson does not exist in bucket",
+              })
+              continue
+            }
+
+            if (
+              status !== "modified" ||
+              !lessonFilesMap.get(slug)!.has(filename)
+            ) {
+              skippedFiles.push({
+                filename: relativePath,
+                status,
+                reason:
+                  status === "modified" ?
+                    "File does not exist in bucket" :
+                    "Structural change in lesson",
+              })
+              continue
+            }
+
+            toSync.push({
+              relativePath,
+              status,
+              bucketPath: `courses/${courseSlug}/exercises/${slug}/${filename}`,
+              isAsset: false,
+            })
+            continue
+          }
+
+          if (relativePath.startsWith(".learn/assets/")) {
+            const bucketPath = `courses/${courseSlug}/${relativePath}`
+            const previousPath = f.previous_filename
+            const previousBucketPath = previousPath ?
+              `courses/${courseSlug}/${previousPath}` :
+              undefined
+
+            toSync.push({
+              relativePath,
+              status,
+              bucketPath,
+              isAsset: true,
+              previousBucketPath,
+            })
+          }
+        }
+
+        const syncedLessonSlugs = new Set<string>()
+        let syncedLessonFilesCount = 0
+        let syncedAssetsUploaded = 0
+        let removedCount = 0
+
+        for (const item of toSync) {
+          if (item.isAsset && item.status === "removed") {
+            try {
+              const fileRef = bucket.file(item.bucketPath)
+              // eslint-disable-next-line no-await-in-loop -- Sequential processing to avoid rate limits
+              await fileRef.delete()
+              removedCount++
+            } catch {
+              // File may not exist, ignore
+            }
+
+            continue
+          }
+
+          if (item.isAsset && item.previousBucketPath) {
+            try {
+              const oldFileRef = bucket.file(item.previousBucketPath)
+              // eslint-disable-next-line no-await-in-loop -- Sequential processing to avoid rate limits
+              await oldFileRef.delete()
+              removedCount++
+            } catch {
+              // Old file may not exist, ignore
+            }
+          }
+
+          if (item.isAsset || item.status === "modified") {
+            let contentRes: { content?: string; encoding?: string }
+            try {
+              // eslint-disable-next-line no-await-in-loop -- Sequential processing to avoid rate limits
+              contentRes = await githubApiFetch(
+                `https://api.github.com/repos/${repository}/contents/${encodeURIComponent(
+                  item.relativePath
+                )}?ref=${targetSHA}`,
+                token
+              )
+            } catch (error: unknown) {
+              const axErr = error as { response?: { status: number } }
+              if (axErr.response?.status === 404) {
+                skippedFiles.push({
+                  filename: item.relativePath,
+                  status: item.status,
+                  reason: "File not found in GitHub",
+                })
+                continue
+              }
+
+              throw error
+            }
+
+            const content = contentRes.content
+            if (!content) {
+              skippedFiles.push({
+                filename: item.relativePath,
+                status: item.status,
+                reason: "No content in response",
+              })
+              continue
+            }
+
+            const buffer = Buffer.from(content, "base64")
+
+            if (isImageFile(item.relativePath)) {
+              // eslint-disable-next-line no-await-in-loop -- Sequential processing to avoid rate limits
+              await uploadBinaryToBucket(
+                bucket,
+                buffer,
+                item.bucketPath,
+                "application/octet-stream"
+              )
+            } else {
+              const text = buffer.toString("utf8")
+              // eslint-disable-next-line no-await-in-loop -- Sequential processing to avoid rate limits
+              await uploadFileToBucket(bucket, text, item.bucketPath)
+            }
+
+            if (item.isAsset) {
+              syncedAssetsUploaded++
+            } else {
+              syncedLessonSlugs.add(
+                item.relativePath.replace(/^exercises\/([^/]+)\/.*/, "$1")
+              )
+              syncedLessonFilesCount++
+            }
+          }
+        }
+
+        configJson.config = configJson.config || {}
+        configJson.config.github = {
+          ...configJson.config.github,
+          lastSyncSHA: targetSHA,
+        }
+        await uploadFileToBucket(
+          bucket,
+          JSON.stringify(configJson),
+          `courses/${courseSlug}/.learn/config.json`
+        )
+
+        return res.json({
+          success: true,
+          syncedLessons: [...syncedLessonSlugs],
+          syncedAssets: syncedAssetsUploaded + removedCount,
+          syncedFiles: syncedLessonFilesCount + syncedAssetsUploaded,
+          removedFiles: removedCount,
+          skippedFiles,
+          newSHA: targetSHA,
+        })
+      })
+    )
+
+    app.post(
+      "/actions/github/push",
+      express.json(),
+      asyncHandler(async (req, res) => {
+        const { courseSlug } = req.body
+
+        if (!courseSlug) {
+          throw new ValidationError("courseSlug is required in request body")
+        }
+
+        const { token, username, isConfigured } = getGithubCredentials()
+        if (!isConfigured || !token || !username) {
+          throw new ValidationError(
+            "GitHub credentials not configured. Set GITHUB_TOKEN and GITHUB_USERNAME in .env"
+          )
+        }
+
+        const configJson = await getConfigJSON(bucket, courseSlug)
+        const repository = configJson.config?.github?.repository
+        const lastSyncSHA = configJson.config?.github?.lastSyncSHA
+        const defaultBranch =
+          configJson.config?.github?.defaultBranch || "main"
+
+        if (!repository || !lastSyncSHA) {
+          throw new ValidationError(
+            "Package has no linked GitHub repository. Create one first."
+          )
+        }
+
+        const refRes = await githubApiFetch(
+          `https://api.github.com/repos/${repository}/git/ref/heads/${defaultBranch}`,
+          token
+        )
+        const currentBranchSHA =
+          refRes.object?.sha ?? refRes.ref?.object?.sha ?? refRes.object?.sha
+        if (!currentBranchSHA) {
+          throw new ValidationError(
+            `Could not get ${defaultBranch} branch SHA from GitHub`
+          )
+        }
+
+        const [allFiles] = await bucket.getFiles({
+          prefix: `courses/${courseSlug}/`,
+        })
+
+        const treeEntries = await Promise.all(
+          allFiles.map(async file => {
+            const [content] = await file.download()
+            const contentBase64 = content.toString("base64")
+
+            const blobRes = await githubApiFetch(
+              `https://api.github.com/repos/${repository}/git/blobs`,
+              token,
+              {
+                method: "POST",
+                body: { content: contentBase64, encoding: "base64" },
+              }
+            )
+
+            const relativePath = file.name.replace(
+              `courses/${courseSlug}/`,
+              ""
+            )
+            return {
+              path: relativePath,
+              mode: "100644",
+              type: "blob",
+              sha: blobRes.sha,
+            }
+          })
+        )
+
+        const treeRes = await githubApiFetch(
+          `https://api.github.com/repos/${repository}/git/trees`,
+          token,
+          {
+            method: "POST",
+            body: { tree: treeEntries },
+          }
+        )
+
+        const commitRes = await githubApiFetch(
+          `https://api.github.com/repos/${repository}/git/commits`,
+          token,
+          {
+            method: "POST",
+            body: {
+              message: "Sync from LearnPack bucket",
+              tree: treeRes.sha,
+              parents: [currentBranchSHA],
+            },
+          }
+        )
+
+        await githubApiFetch(
+          `https://api.github.com/repos/${repository}/git/refs/heads/${defaultBranch}`,
+          token,
+          {
+            method: "PATCH",
+            body: { sha: commitRes.sha, force: false },
+          }
+        )
+
+        configJson.config = configJson.config || {}
+        configJson.config.github = {
+          ...configJson.config.github,
+          lastSyncSHA: commitRes.sha,
+        }
+        await uploadFileToBucket(
+          bucket,
+          JSON.stringify(configJson),
+          `courses/${courseSlug}/.learn/config.json`
+        )
+
+        return res.json({
+          success: true,
+          repository,
+          sha: commitRes.sha,
+          totalFiles: allFiles.length,
+        })
+      })
+    )
+
     app.get("/proxy", async (req, res) => {
       const { url } = req.query