@learnpack/learnpack 5.0.352 → 5.0.353

package/lib/commands/publish.js

@@ -445,6 +445,12 @@ class BuildCommand extends SessionCommand_1.default {
             this.log(`Build completed: ${zipFilePath} (${archive.pointer()} total bytes)`);
             // Remove build directory after zip is created
             console_1.default.debug("Zip file saved in project root");
+            // TODO(#2103): this CLI path publishes without the guarantees the
+            // creator flow has. It builds no package-manifest.json (pre-existing), it
+            // does not run the descriptions stage, and it emits neither
+            // package_published nor package_manifest_updated, so breathecode never
+            // hears about these publications. Decide between parity, deferring the
+            // work to the sweep, or documenting this path as degraded.
             const formData = new FormData();
             formData.append("file", fs.createReadStream(zipFilePath));
             formData.append("config", JSON.stringify(learnJson));

package/lib/commands/serve.js

@@ -34,6 +34,11 @@ const sidebarGenerator_1 = require("../utils/sidebarGenerator");
 const publish_1 = require("./publish");
 const export_1 = require("../utils/export");
 const packageManifest_1 = require("../utils/packageManifest");
+const gcsBucketName_1 = require("../utils/gcsBucketName");
+const syllabusSync_1 = require("../utils/syllabusSync");
+const publishJournal_1 = require("../utils/publishJournal");
+const publishStage_1 = require("../utils/descriptions/publishStage");
+const publishEvents_1 = require("../utils/publishEvents");
 const errorHandler_1 = require("../utils/errorHandler");
 const jsdom_1 = require("jsdom");
 const redis_1 = require("redis");
@@ -97,7 +102,7 @@ const createLearnJson = (courseInfo) => {
         },
         grading: "isolated",
         telemetry: {
-            batch: "https://breathecode.herokuapp.com/v1/assignment/me/telemetry",
+            batch: api_1.BREATHECODE_TELEMETRY_URL,
         },
         preview: expectedPreviewUrl,
     };
@@ -932,7 +937,7 @@ class ServeCommand extends SessionCommand_1.default {
         const bucketStorage = new storage_1.Storage({
             credentials,
         });
-        const bucket = bucketStorage.bucket(process.env.GCP_BUCKET_NAME || "learnpack-packages");
+        const bucket = bucketStorage.bucket((0, gcsBucketName_1.requireGcsBucketName)());
         const rawHost = process.env.HOST || "";
         const host = rawHost.trim().split(/\s+#/)[0].trim();
         if (!host) {
@@ -3264,245 +3269,15 @@ class ServeCommand extends SessionCommand_1.default {
                 return res.status(400).json({ error: "Course slug is required" });
             }
             try {
-                // Get the current syllabus
+                // Reconciliation logic extracted to src/utils/syllabusSync.ts so the
+                // sweep/backfill can reuse it. The manual dev button keeps the original
+                // destructive behavior via prune: true.
                 const syllabus = await getSyllabus(courseSlug, bucket);
-                const removedLessons = [];
-                const keptLessons = [];
-                const duplicatesRemoved = [];
-                const addedLessons = [];
-                let repairedTranslationsInLessons = 0;
-                let repairedTranslationEntries = 0;
-                let fixedLessons = 0;
-                console.log(`📋 Checking ${syllabus.lessons.length} lessons in syllabus...`);
-                // First pass: Check each lesson to see if it exists in the bucket and count files.
-                // We try two possible folder names because they can differ by source:
-                // - Initial upload / most flows: folder = slugify(lesson.id + "-" + lesson.title)
-                // - create-step flow: folder = lesson.uid (Rigo's stepSlug), which may not match slugify()
-                //   (e.g. casing or character handling). GCS prefixes are case-sensitive.
-                const existingLessons = [];
-                for (const lesson of syllabus.lessons) {
-                    const lessonSlug = (0, creatorUtilities_2.slugify)(lesson.id + "-" + lesson.title);
-                    let filePrefix = `courses/${courseSlug}/exercises/${lessonSlug}/`;
-                    // eslint-disable-next-line no-await-in-loop
-                    let [files] = await bucket.getFiles({
-                        prefix: filePrefix,
-                    });
-                    if (files.length === 0 && lesson.uid) {
-                        filePrefix = `courses/${courseSlug}/exercises/${lesson.uid}/`;
-                        // eslint-disable-next-line no-await-in-loop
-                        [files] = await bucket.getFiles({ prefix: filePrefix });
-                    }
-                    const resolvedSlug = files.length > 0 ?
-                        filePrefix
-                            .replace(`courses/${courseSlug}/exercises/`, "")
-                            .replace(/\/$/, "") :
-                        lessonSlug;
-                    if (files.length === 0) {
-                        removedLessons.push({
-                            id: lesson.id,
-                            title: lesson.title,
-                            slug: lessonSlug,
-                        });
-                        console.log(`❌ Lesson not found: ${lessonSlug}${lesson.uid ? ` (also tried uid: ${lesson.uid})` : ""}`);
-                    }
-                    else {
-                        existingLessons.push({
-                            lesson,
-                            slug: resolvedSlug,
-                            fileCount: files.length,
-                        });
-                        console.log(`✅ Lesson exists: ${resolvedSlug} (${files.length} files)`);
-                    }
-                }
-                // Second pass: Detect and resolve duplicates
-                const slugMap = new Map();
-                // Group by slug
-                for (const item of existingLessons) {
-                    if (!slugMap.has(item.slug)) {
-                        slugMap.set(item.slug, []);
-                    }
-                    slugMap.get(item.slug).push(item);
-                }
-                // Process each group
-                for (const [slug, items] of slugMap.entries()) {
-                    if (items.length > 1) {
-                        // Duplicates found! Sort by file count (descending) and keep the most complete
-                        items.sort((a, b) => b.fileCount - a.fileCount);
-                        const winner = items[0];
-                        const losers = items.slice(1);
-                        console.log(`🔍 Duplicate slug detected: ${slug}`);
-                        console.log(`   ✅ Keeping: ${winner.lesson.id} - ${winner.lesson.title} (${winner.fileCount} files)`);
-                        // Keep the winner
-                        keptLessons.push({
-                            id: winner.lesson.id,
-                            title: winner.lesson.title,
-                            slug: winner.slug,
-                            fileCount: winner.fileCount,
-                        });
-                        // Mark losers for removal
-                        for (const loser of losers) {
-                            console.log(`   ❌ Removing duplicate: ${loser.lesson.id} - ${loser.lesson.title} (${loser.fileCount} files)`);
-                            duplicatesRemoved.push({
-                                id: loser.lesson.id,
-                                title: loser.lesson.title,
-                                slug: loser.slug,
-                                fileCount: loser.fileCount,
-                            });
-                        }
-                    }
-                    else {
-                        // No duplicates, keep as is
-                        keptLessons.push({
-                            id: items[0].lesson.id,
-                            title: items[0].lesson.title,
-                            slug: items[0].slug,
-                            fileCount: items[0].fileCount,
-                        });
-                    }
-                }
-                // Update syllabus: keep only the winners and remove non-existent + duplicates
-                const totalRemoved = removedLessons.length + duplicatesRemoved.length;
-                if (totalRemoved > 0) {
-                    syllabus.lessons = syllabus.lessons.filter(lesson => {
-                        const lessonSlug = (0, creatorUtilities_2.slugify)(lesson.id + "-" + lesson.title);
-                        const isRemoved = removedLessons.some(removed => removed.slug === lessonSlug);
-                        const isDuplicate = duplicatesRemoved.some(dup => dup.id === lesson.id && dup.title === lesson.title);
-                        return !isRemoved && !isDuplicate;
-                    });
-                }
-                // Third pass: add lessons that exist in the bucket but are missing from the syllabus
-                const existingSlugs = new Set(existingLessons.map(e => e.slug));
-                const exercisesPrefix = `courses/${courseSlug}/exercises/`;
-                const [allExerciseFiles] = await bucket.getFiles({
-                    prefix: exercisesPrefix,
-                });
-                const bucketFolderSlugs = new Set();
-                for (const file of allExerciseFiles) {
-                    if (!file.name.startsWith(exercisesPrefix))
-                        continue;
-                    const afterPrefix = file.name.slice(exercisesPrefix.length);
-                    const segment = afterPrefix.split("/")[0];
-                    if (segment)
-                        bucketFolderSlugs.add(segment);
-                }
-                for (const folderSlug of bucketFolderSlugs) {
-                    if (existingSlugs.has(folderSlug))
-                        continue;
-                    const idMatch = folderSlug.match(/^(\d+(?:\.\d+)?)(?:-(.*))?$/);
-                    const id = idMatch ? idMatch[1] : folderSlug;
-                    const titlePart = idMatch && idMatch[2] ? idMatch[2] : folderSlug;
-                    const title = titlePart.replace(/-/g, " ").trim() || folderSlug;
-                    const newLesson = {
-                        id,
-                        uid: folderSlug,
-                        title,
-                        type: "READ",
-                        description: title,
-                        duration: 2,
-                        generated: true,
-                        status: "DONE",
-                    };
-                    syllabus.lessons.push(newLesson);
-                    addedLessons.push({ id, title, slug: folderSlug });
-                    console.log(`➕ Added missing lesson from bucket: ${folderSlug}`);
-                }
-                if (addedLessons.length > 0) {
-                    syllabus.lessons.sort((a, b) => {
-                        const na = parseFloat(a.id);
-                        const nb = parseFloat(b.id);
-                        if (!Number.isNaN(na) && !Number.isNaN(nb))
-                            return na - nb;
-                        return String(a.id).localeCompare(String(b.id));
-                    });
-                }
-                // 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 (0, configBuilder_1.buildConfig)(bucket, courseSlug);
-                    const translationsBySlug = new Map();
-                    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 = [
-                            (0, creatorUtilities_2.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;
-                        }
-                    }
-                    // Fifth pass: fix lessons stuck in GENERATING or ERROR when the file exists in the bucket
-                    const primaryLanguage = syllabus.courseInfo.language || "en";
-                    for (const lesson of syllabus.lessons) {
-                        if (lesson.generated !== false)
-                            continue;
-                        if (lesson.status !== "GENERATING" && lesson.status !== "ERROR")
-                            continue;
-                        const candidateSlugs = [
-                            (0, creatorUtilities_2.slugify)(lesson.id + "-" + lesson.title),
-                            lesson.uid,
-                        ].filter(Boolean);
-                        const matchedSlug = candidateSlugs.find(s => translationsBySlug.has(s));
-                        if (!matchedSlug)
-                            continue;
-                        const langs = translationsBySlug.get(matchedSlug) || [];
-                        if (!langs.includes(primaryLanguage))
-                            continue;
-                        const prevStatus = lesson.status;
-                        lesson.generated = true;
-                        lesson.status = "DONE";
-                        fixedLessons += 1;
-                        console.log(`🔧 Fixed lesson: ${lesson.id} - "${lesson.title}" (was generated:false status:${prevStatus}, primary language "${primaryLanguage}" exists in bucket)`);
-                    }
-                }
-                catch (error) {
-                    console.error("⚠️ Could not reconcile lesson translations during syllabus sync:", error);
-                }
-                if (totalRemoved > 0 ||
-                    addedLessons.length > 0 ||
-                    repairedTranslationsInLessons > 0 ||
-                    fixedLessons > 0) {
-                    await saveSyllabus(courseSlug, syllabus, bucket);
-                    console.log(`✅ Syllabus synchronized. Removed ${removedLessons.length} non-existent, ${duplicatesRemoved.length} duplicate(s); added ${addedLessons.length} from bucket; repaired translations in ${repairedTranslationsInLessons} lesson(s); fixed ${fixedLessons} stuck lesson(s).`);
+                const storage = (0, syllabusSync_1.createGcsSyllabusSyncStorage)(bucket);
+                const result = await (0, syllabusSync_1.synchronizeSyllabusWithBucket)(storage, courseSlug, syllabus, { prune: true });
+                if (result.changed) {
+                    await saveSyllabus(courseSlug, result.syllabus, bucket);
+                    console.log(`✅ Syllabus synchronized. Removed ${result.counters.removedLessons} non-existent + duplicate(s); added ${result.counters.addedLessons} from bucket; repaired translations in ${result.counters.repairedTranslationsInLessons} lesson(s); fixed ${result.counters.fixedLessons} stuck lesson(s).`);
                 }
                 else {
                     console.log(`✅ Syllabus is already in sync. No changes.`);
@@ -3510,18 +3285,18 @@ class ServeCommand extends SessionCommand_1.default {
                 res.json({
                     status: "SUCCESS",
                     message: `Syllabus synchronized successfully`,
-                    totalLessons: syllabus.lessons.length,
-                    keptLessons: keptLessons.length,
-                    removedLessons: removedLessons.length,
-                    duplicatesResolved: duplicatesRemoved.length,
-                    addedLessons: addedLessons.length,
-                    fixedLessons,
-                    repairedTranslationsInLessons,
-                    repairedTranslationEntries,
-                    removed: removedLessons,
-                    duplicates: duplicatesRemoved,
-                    kept: keptLessons,
-                    added: addedLessons,
+                    totalLessons: result.counters.totalLessons,
+                    keptLessons: result.counters.keptLessons,
+                    removedLessons: result.counters.removedLessons,
+                    duplicatesResolved: result.counters.duplicatesResolved,
+                    addedLessons: result.counters.addedLessons,
+                    fixedLessons: result.counters.fixedLessons,
+                    repairedTranslationsInLessons: result.counters.repairedTranslationsInLessons,
+                    repairedTranslationEntries: result.counters.repairedTranslationEntries,
+                    removed: result.details.removed,
+                    duplicates: result.details.duplicates,
+                    kept: result.details.kept,
+                    added: result.details.added,
                 });
             }
             catch (error) {
@@ -3906,6 +3681,10 @@ class ServeCommand extends SessionCommand_1.default {
                 const buildRoot = path.join(tmpRoot, "build");
                 rimraf.sync(tmpRoot);
                 mkdirp.sync(buildRoot);
+                // Bookkeeping for the whole publication, so an interrupted run can be
+                // resumed. Best effort: never blocks the publish.
+                const journalStorage = (0, publishJournal_1.createGcsJournalStorage)(bucket);
+                const journal = await (0, publishJournal_1.createJournal)(journalStorage, slug);
                 // 4) Copiar UI descomprimida (_app)
                 const uiSrc = path.resolve(__dirname, "../ui/_app");
                 const copyDir = (src, dest) => {
@@ -3957,10 +3736,15 @@ class ServeCommand extends SessionCommand_1.default {
                     const [buf] = await file.download();
                     fs.writeFileSync(out, buf);
                 }));
-                await (0, packageManifest_1.generateAndPersistPackageManifest)(bucket, slug, {
+                const publishedManifest = await (0, packageManifest_1.generateAndPersistPackageManifest)(bucket, slug, {
                     publishedAt: new Date().toISOString(),
                     localDir: buildRoot,
                 });
+                // Decide here, while the build is still on disk, whether this package
+                // will need descriptions: the answer is what the response and the
+                // package_published event promise to breathecode.
+                const pendingDescriptions = (0, publishStage_1.countPendingDescriptions)(buildRoot, exercises);
+                const descriptionsOutcome = pendingDescriptions > 0 ? "queued" : "up_to_date";
                 // 8) Crear el config.json en buildRoot con lo que retorna buildConfig
                 const fullConfig = { config, exercises };
                 fullConfig.config.slug = slug;
@@ -3984,10 +3768,16 @@ class ServeCommand extends SessionCommand_1.default {
                             headers: Object.assign(Object.assign({}, form.getHeaders()), { Authorization: "Token " + rigoToken.trim() }),
                         });
                         rigoPublishUrl = rigoRes.data.url;
+                        await (0, publishJournal_1.markStage)(journalStorage, journal, "deploy", "done", {
+                            meta: { url: rigoPublishUrl },
+                        });
                         let errors;
                         try {
                             const assetResults = await createMultiLangAsset(bucket, rigoToken, bcToken, slug, fullConfig.config, rigoRes.data.url, academyId);
                             errors = assetResults.errors;
+                            await (0, publishJournal_1.markStage)(journalStorage, journal, "assetsSync", errors.length > 0 ? "failed" : "done", {
+                                error: errors.length > 0 ? JSON.stringify(errors) : undefined,
+                            });
                         }
                         catch (error) {
                             console.error("Asset sync failed unexpectedly:", error);
@@ -3997,17 +3787,52 @@ class ServeCommand extends SessionCommand_1.default {
                                     error: { detail: "Asset sync failed unexpectedly." },
                                 },
                             ];
+                            await (0, publishJournal_1.markStage)(journalStorage, journal, "assetsSync", "failed", {
+                                error: error.message,
+                            });
                         }
-                        if (res.headersSent)
-                            return;
-                        console.log("RigoRes", rigoRes.data);
-                        res.json({
-                            url: rigoPublishUrl,
-                            errors,
+                        if (!res.headersSent) {
+                            console.log("RigoRes", rigoRes.data);
+                            res.json({
+                                url: rigoPublishUrl,
+                                errors,
+                                descriptions: descriptionsOutcome,
+                            });
+                        }
+                        // The package is published: tell breathecode, announcing whether a
+                        // second event is coming. Emitted after the asset sync so the
+                        // assets the payload refers to already exist.
+                        const eventContext = {
+                            publishId: journal.publishId,
+                            courseSlug: slug,
+                            packageInfo: await (0, publishEvents_1.fetchPackageInfo)(slug, rigoToken),
+                            manifest: publishedManifest,
+                        };
+                        const publishedDelivered = await (0, publishEvents_1.sendPublishEvent)((0, publishEvents_1.buildPackagePublishedEvent)(eventContext, descriptionsOutcome), bcToken);
+                        await (0, publishJournal_1.markStage)(journalStorage, journal, "publishedEvent", publishedDelivered ? "done" : "failed", {
+                            error: publishedDelivered ? undefined : "delivery failed",
+                            // Recorded so a sweep resuming this publication knows whether a
+                            // manifest event was promised to breathecode.
+                            meta: { descriptions: descriptionsOutcome },
+                        });
+                        // Stage B, after responding: a course may need several ~15s
+                        // completions, far past any request limit. The package is already
+                        // published and durable; this only enriches it.
+                        (0, publishStage_1.runDescriptionsStageAfterPublish)({
+                            courseSlug: slug,
+                            gcsBucket: bucket,
+                            journal,
+                            journalStorage,
+                            hasWork: pendingDescriptions > 0,
+                            eventContext,
+                            breathecodeToken: bcToken,
+                        }).catch(error => {
+                            console.error("[descriptions] Detached stage rejected:", error);
                         });
                     }
                     catch (error) {
                         console.error(error);
+                        await (0, publishJournal_1.markStage)(journalStorage, journal, rigoPublishUrl === undefined ? "deploy" : "assetsSync", "failed", { error: error.message });
                         if (res.headersSent)
                             return;
                         if (rigoPublishUrl !== undefined) {
@@ -4019,6 +3844,7 @@ class ServeCommand extends SessionCommand_1.default {
                                         error: { detail: "Asset sync failed unexpectedly." },
                                     },
                                 ],
+                                descriptions: descriptionsOutcome,
                             });
                         }
                         else {

package/lib/models/creator.d.ts

@@ -36,6 +36,12 @@ export interface Lesson {
             startedAt: number;
             completedAt?: number;
             error?: boolean;
+            description?: string | null;
+            descriptionStatus?: "generated" | "pending" | "error" | "none";
+            sourceContentHash?: string;
+            sourceSimHash?: string;
+            descriptionPromptVersion?: number;
+            descriptionSource?: "auto" | "human";
         };
     };
     syncNotifications?: SyncNotification[];

package/lib/scripts/descriptionsGcsBackfill.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/scripts/descriptionsGcsBackfill.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable no-await-in-loop */
+/**
+ * Fase 0b — GCS descriptions backfill (reuse from S3, no LLM).
+ *
+ * Seeds the GCS (draft) syllabus with descriptions already generated for the
+ * published S3 syllabus (Fase 0a) — a pure COPY, guarded by the content hash,
+ * performed by the shared mirror (`mirrorDescriptionsToDraft`). It NEVER calls
+ * the LLM: the ~800 GCS drafts are mostly unused, so anything not reusable from
+ * S3 is left for the next publication of that course (or a single-slug 0a run).
+ * Run AFTER 0a has completed.
+ *
+ * Batched like 0a: --limit courses per run (default 50), ordered by
+ * initialSyllabus modification time (newest first).
+ *
+ * Secrets/infra via env: GCP_CREDENTIALS_JSON (required), plus
+ * S3_PACKAGES_BUCKET / GCP_BUCKET_NAME / AWS_REGION as fallbacks for the
+ * corresponding flags.
+ *
+ * Per-run flags:
+ *   --s3-bucket <name>   published S3 bucket to reuse from (or env S3_PACKAGES_BUCKET)
+ *   --gcs-bucket <name>  GCS bucket (or env GCP_BUCKET_NAME, which is required)
+ *   --region <region>    AWS region (default us-east-1, or env AWS_REGION)
+ *   --slug <slug>        process a single course
+ *   --limit <n>          courses per run (default 50)
+ *   --dry-run            preview without writing
+ *   --no-reconcile       skip the additive syllabus reconciliation
+ *
+ * Examples:
+ *   node lib/scripts/descriptionsGcsBackfill.js --limit 200
+ *   node lib/scripts/descriptionsGcsBackfill.js --slug my-course
+ */
+const node_util_1 = require("node:util");
+const storage_1 = require("@google-cloud/storage");
+const client_s3_1 = require("@aws-sdk/client-s3");
+const syllabusSync_1 = require("../utils/syllabusSync");
+const packageManifestBackfill_1 = require("../utils/s3/packageManifestBackfill");
+const gcsBucketName_1 = require("../utils/gcsBucketName");
+const gcsStorage_1 = require("../utils/descriptions/gcsStorage");
+const mirrorDescriptions_1 = require("../utils/descriptions/mirrorDescriptions");
+const s3Storage_1 = require("../utils/descriptions/s3Storage");
+const GCS_SYLLABUS_PATTERN = /^courses\/([^/]+)\/\.learn\/initialSyllabus\.json$/;
+/** Courses (by slug) ordered by initialSyllabus.json update time, newest first. */
+async function listCoursesByRecency(bucket) {
+    var _a;
+    const [files] = await bucket.getFiles({ prefix: "courses/" });
+    const mtimes = new Map();
+    for (const file of files) {
+        const match = file.name.match(GCS_SYLLABUS_PATTERN);
+        if (match) {
+            const updated = (_a = file.metadata) === null || _a === void 0 ? void 0 : _a.updated;
+            mtimes.set(match[1], updated ? new Date(updated).getTime() : 0);
+        }
+    }
+    return [...mtimes.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(entry => entry[0]);
+}
+async function main() {
+    var _a, _b;
+    const { values } = (0, node_util_1.parseArgs)({
+        options: {
+            "s3-bucket": { type: "string" },
+            "gcs-bucket": { type: "string" },
+            region: { type: "string" },
+            slug: { type: "string" },
+            limit: { type: "string" },
+            "dry-run": { type: "boolean", default: false },
+            "no-reconcile": { type: "boolean", default: false },
+        },
+    });
+    const s3Bucket = values["s3-bucket"] ||
+        process.env.S3_PACKAGES_BUCKET ||
+        "learnpack-paquetes";
+    const credentialsEnv = process.env.GCP_CREDENTIALS_JSON;
+    if (!credentialsEnv) {
+        console.error("[gcs-backfill] GCP_CREDENTIALS_JSON (env) is required");
+        process.exit(1);
+    }
+    const bucket = new storage_1.Storage({
+        credentials: JSON.parse(credentialsEnv),
+    }).bucket(values["gcs-bucket"] || (0, gcsBucketName_1.requireGcsBucketName)());
+    const s3 = new client_s3_1.S3Client({
+        region: values.region || process.env.AWS_REGION || "us-east-1",
+    });
+    const dryRun = (_a = values["dry-run"]) !== null && _a !== void 0 ? _a : false;
+    const reconcile = !((_b = values["no-reconcile"]) !== null && _b !== void 0 ? _b : false);
+    const limit = Number.parseInt(values.limit || "50", 10) || 50;
+    const storage = (0, gcsStorage_1.createGcsDescriptionsStorage)(bucket);
+    const singleSlug = values.slug;
+    const slugs = singleSlug ? [singleSlug] : await listCoursesByRecency(bucket);
+    console.log(`[gcs-backfill] Starting${singleSlug ? ` (slug=${singleSlug})` : ` (limit=${limit})`}${dryRun ? " (dry-run)" : ""} over ${slugs.length} candidate course(s)`);
+    let processed = 0;
+    let copied = 0;
+    let missed = 0;
+    for (const slug of slugs) {
+        if (!singleSlug && processed >= limit) {
+            break;
+        }
+        try {
+            const publishedSyllabus = await (0, packageManifestBackfill_1.fetchJsonObject)(s3, s3Bucket, (0, s3Storage_1.syllabusKey)(slug));
+            if (!publishedSyllabus) {
+                continue;
+            }
+            if (reconcile && storage.syllabusSyncStorage) {
+                const draft = await storage.readSyllabus(slug);
+                if (draft) {
+                    try {
+                        const sync = await (0, syllabusSync_1.synchronizeSyllabusWithBucket)(storage.syllabusSyncStorage, slug, draft, { prune: false });
+                        if (sync.changed && !dryRun) {
+                            await storage.writeSyllabus(slug, sync.syllabus);
+                        }
+                    }
+                    catch (error) {
+                        console.error(`[gcs-backfill] Reconciliation failed for "${slug}":`, error.message);
+                    }
+                }
+            }
+            const result = await (0, mirrorDescriptions_1.mirrorDescriptionsToDraft)(storage, slug, publishedSyllabus, { dryRun });
+            if (result.copied === 0 && result.missed === 0) {
+                continue;
+            }
+            processed += 1;
+            copied += result.copied;
+            missed += result.missed;
+            console.log(`[gcs-backfill] "${slug}": copied ${result.copied}, ${result.missed} miss(es)${dryRun ? " (dry-run)" : ""}`);
+        }
+        catch (error) {
+            processed += 1;
+            console.error(`[gcs-backfill] Failed processing "${slug}":`, error.message);
+        }
+    }
+    console.log(`[gcs-backfill] Done. ${processed} course(s), ${copied} description(s) copied, ${missed} miss(es).`);
+}
+main()
+    .then(() => process.exit(0))
+    .catch(error => {
+    console.error("[gcs-backfill] Fatal error:", error);
+    process.exit(1);
+});

package/lib/scripts/descriptionsS3Backfill.d.ts

@@ -0,0 +1 @@
+export {};